Make git repo
This commit is contained in:
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Fedora 42 Custom Live ISO Builder
|
||||
|
||||
A Makefile-based toolchain for building custom Fedora 42 live ISOs optimized for specific use cases like Point-of-Sale systems, kiosks, security workstations, and minimal servers.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install dependencies (requires Fedora)
|
||||
sudo make deps
|
||||
|
||||
# Generate kickstart templates
|
||||
make init-kickstarts
|
||||
|
||||
# Build minimal ISO
|
||||
sudo make iso VARIANT=minimal
|
||||
|
||||
# Test in QEMU
|
||||
make test-qemu
|
||||
```
|
||||
|
||||
## Available Variants
|
||||
|
||||
| Variant | Description | Approx Size |
|
||||
| ------------- | ---------------------------------------- | ----------- |
|
||||
| `minimal` | Bare minimum bootable system with SSH | ~400MB |
|
||||
| `kiosk` | Single-app kiosk/PoS with Cage + Firefox | ~800MB |
|
||||
| `workstation` | Lightweight GUI with Sway | ~1.2GB |
|
||||
| `security` | Security/forensics toolkit | ~1.5GB |
|
||||
|
||||
## Requirements
|
||||
|
||||
- Fedora 42 (or compatible) host system
|
||||
- Root privileges for ISO creation
|
||||
- ~10GB free disk space
|
||||
- KVM support recommended (or use `iso-novirt`)
|
||||
|
||||
## Usage
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# Build with default (minimal) variant
|
||||
sudo make iso
|
||||
|
||||
# Build specific variant
|
||||
sudo make iso VARIANT=kiosk
|
||||
sudo make iso VARIANT=workstation
|
||||
sudo make iso VARIANT=security
|
||||
|
||||
# Use custom kickstart
|
||||
sudo make iso KICKSTART=/path/to/custom.ks
|
||||
|
||||
# Build without KVM (slower, works in containers)
|
||||
sudo make iso-novirt VARIANT=minimal
|
||||
```
|
||||
|
||||
### Utility Commands
|
||||
|
||||
```bash
|
||||
# Validate kickstart syntax
|
||||
make validate KICKSTART=kickstarts/minimal.ks
|
||||
|
||||
# Test ISO in QEMU
|
||||
make test-qemu
|
||||
|
||||
# Generate checksums
|
||||
make checksum
|
||||
|
||||
# Show configuration
|
||||
make info
|
||||
|
||||
# Clean build artifacts
|
||||
make clean
|
||||
sudo make distclean # Also removes output/
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Modifying Kickstarts
|
||||
|
||||
The kickstart files in `kickstarts/` control the entire OS configuration:
|
||||
|
||||
1. **Packages**: Add/remove packages in the `%packages` section
|
||||
2. **Services**: Enable/disable systemd units in `%post`
|
||||
3. **Users**: Configure users and authentication
|
||||
4. **Partitioning**: Customize disk layout
|
||||
|
||||
### Adding Custom Files
|
||||
|
||||
1. Place files in `overlays/<variant>/`
|
||||
2. Copy them in the `%post` section of your kickstart
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
%post
|
||||
# Copy custom configs
|
||||
cp -r /run/install/repo/overlays/* /
|
||||
%end
|
||||
```
|
||||
|
||||
### Creating New Variants
|
||||
|
||||
1. Create `kickstarts/myvariant.ks`
|
||||
2. Build with `sudo make iso VARIANT=myvariant`
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── Makefile # Build system
|
||||
├── README.md
|
||||
├── kickstarts/ # Kickstart definitions
|
||||
│ ├── minimal.ks
|
||||
│ ├── kiosk.ks
|
||||
│ ├── workstation.ks
|
||||
│ └── security.ks
|
||||
├── overlays/ # Files to include in ISO
|
||||
├── build/ # Temporary build files
|
||||
├── cache/ # Downloaded packages (preserved)
|
||||
└── output/ # Final ISO files
|
||||
└── fedora-42-custom-*.iso
|
||||
```
|
||||
|
||||
## PoS/Kiosk Specific Notes
|
||||
|
||||
For Point-of-Sale or kiosk deployments:
|
||||
|
||||
### Security Hardening
|
||||
|
||||
```kickstart
|
||||
%post
|
||||
# Disable USB storage
|
||||
echo "blacklist usb-storage" > /etc/modprobe.d/blacklist-usb.conf
|
||||
|
||||
# Disable Ctrl+Alt+Del reboot
|
||||
systemctl mask ctrl-alt-del.target
|
||||
|
||||
# Read-only root filesystem (advanced)
|
||||
# Add 'ro' to kernel cmdline and use overlayfs
|
||||
%end
|
||||
```
|
||||
|
||||
### Auto-start Application
|
||||
|
||||
The `kiosk` variant uses Cage (minimal Wayland compositor) to run Firefox in kiosk mode. Modify `/home/kiosk/.bash_profile` to launch your application:
|
||||
|
||||
```bash
|
||||
# For a custom app
|
||||
exec cage -- /usr/local/bin/my-pos-app
|
||||
|
||||
# For a web app
|
||||
exec cage -- firefox --kiosk https://pos.example.com
|
||||
|
||||
# For Electron apps
|
||||
exec cage -- /opt/myapp/myapp --kiosk
|
||||
```
|
||||
|
||||
### Network Configuration
|
||||
|
||||
For static IP (common in PoS):
|
||||
|
||||
```kickstart
|
||||
network --bootproto=static --ip=192.168.1.100 --netmask=255.255.255.0 \
|
||||
--gateway=192.168.1.1 --nameserver=192.168.1.1 --device=link
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build fails with "No space left on device"
|
||||
|
||||
The build uses `/var/tmp/lorax-build` by default. Either:
|
||||
|
||||
- Free space on that partition
|
||||
- Change `TMP_DIR` in Makefile to a larger partition
|
||||
|
||||
### "Cannot find a valid baseurl"
|
||||
|
||||
Network issues or mirror problems. Try:
|
||||
|
||||
```bash
|
||||
# Use a specific mirror
|
||||
sudo make iso LORAX_REPO=https://mirror.example.com/fedora/42/Everything/x86_64/os/
|
||||
```
|
||||
|
||||
### SELinux denials
|
||||
|
||||
If building in a container or restricted environment:
|
||||
|
||||
```bash
|
||||
# Temporarily set permissive (not recommended for production)
|
||||
sudo setenforce 0
|
||||
sudo make iso
|
||||
sudo setenforce 1
|
||||
```
|
||||
|
||||
### ISO won't boot
|
||||
|
||||
1. Verify checksum: `make checksum`
|
||||
2. Check implanted MD5: `checkisomd5 output/*.iso`
|
||||
3. Review build log: `less build/livemedia.log`
|
||||
|
||||
## Advanced: Building in Containers
|
||||
|
||||
For reproducible builds in CI/CD:
|
||||
|
||||
```bash
|
||||
podman run --rm -it --privileged \
|
||||
-v $(pwd):/build:Z \
|
||||
-v /dev:/dev \
|
||||
registry.fedoraproject.org/fedora:42 \
|
||||
bash -c "cd /build && make deps && make iso-novirt"
|
||||
```
|
||||
|
||||
Note: Container builds require `--privileged` for loop devices and must use `iso-novirt`.
|
||||
|
||||
## License
|
||||
|
||||
MIT - Do whatever you want with this.
|
||||
Reference in New Issue
Block a user