Charles N Wyble
546c3ea5cf
Adds docs/BUILD-DOCUMENTATION.md explaining: - Directory structure (clean and organized) - Complete build process (5 steps) - Preseed configuration details - ISO deployment procedures (bare metal and VM) - Docker container usage (dev and test) - Security features applied during installation - Troubleshooting guide - Next steps for deployment This replaces all scattered old documentation with a single, comprehensive reference for the ISO-based build system. 💘 Generated with Crush Assisted-by: Gemini 2.5 Flash via Crush <crush@charm.land>
279 lines
7.8 KiB
Markdown
279 lines
7.8 KiB
Markdown
# Football ISO Build Documentation
|
|
|
|
## Overview
|
|
|
|
Football uses an ISO-based installer approach with embedded preseed configuration. The build system creates a bootable Debian installer ISO that automates most of the installation process.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
football/
|
|
├── AGENTS.md # Main project documentation (AI agent reference)
|
|
├── README.md # Quick start guide
|
|
├── LICENSE # License file
|
|
├── .gitignore # Git ignore rules
|
|
├── .dockerignore # Docker ignore rules
|
|
│
|
|
├── scripts/ # Build and test scripts
|
|
│ ├── build-iso.sh # Main ISO build script (Docker-based)
|
|
│ └── test-iso.sh # ISO testing script (QEMU VM boot)
|
|
│
|
|
├── config/ # Configuration files
|
|
│ └── preseed.cfg # Debian preseed automation file
|
|
│
|
|
├── docs/ # Documentation
|
|
│ ├── COMPLIANCE.md # Compliance requirements
|
|
│ ├── INCIDENT-RESPONSE.md # Incident response procedures
|
|
│ ├── SECURITY-BASELINES.md # Security baselines
|
|
│ ├── SECURITY-POLICY.md # Security policies
|
|
│ ├── TEST-EVIDENCE.md # Test evidence and results
|
|
│ └── old/ # Archived old documentation
|
|
│
|
|
├── tests/ # Test scripts
|
|
│ ├── verify-compliance.sh # Compliance verification
|
|
│ ├── compliance-test.sh # Full compliance test suite
|
|
│ └── build-and-test.sh # VM-based testing
|
|
│
|
|
├── keys/ # WireGuard keys (generated by users)
|
|
│
|
|
├── logs/ # Build and test logs
|
|
│
|
|
├── output/ # Build output artifacts
|
|
│ └── football-installer.iso (generated by build-iso.sh)
|
|
│
|
|
├── iso-tmp/ # Temporary ISO build directory (in .gitignore)
|
|
│
|
|
├── Dockerfile.dev # Fat development container
|
|
└── Dockerfile.test # Test container
|
|
```
|
|
|
|
## Build Process
|
|
|
|
### Step 1: Create Preseed Configuration
|
|
|
|
The `config/preseed.cfg` file contains Debian installer automation:
|
|
|
|
- **Automated Steps** (no user interaction required):
|
|
- Locale and language settings
|
|
- Network configuration (DHCP)
|
|
- Partitioning (LVM, auto)
|
|
- Timezone
|
|
- Package selection
|
|
- Boot loader installation
|
|
|
|
- **Manual Steps** (user must provide):
|
|
- Username creation
|
|
- User password (min 12 chars, mixed case, numbers, special chars)
|
|
- Root password (min 12 chars, mixed case, numbers, special chars)
|
|
- Target disk/partition selection
|
|
|
|
### Step 2: Build ISO
|
|
|
|
Run `./scripts/build-iso.sh` which:
|
|
|
|
1. **Downloads Debian ISO** (in Docker)
|
|
- Fetches Debian netinst ISO from official mirrors
|
|
- Uses sid/testing (Debian 13 is still testing)
|
|
|
|
2. **Extracts ISO** (in Docker)
|
|
- Extracts ISO contents to temporary directory
|
|
- Preserves ISO structure
|
|
|
|
3. **Injects Preseed** (in Docker)
|
|
- Copies `config/preseed.cfg` to ISO root
|
|
- Modifies `isolinux/isolinux.cfg` to auto-load preseed
|
|
- Sets default boot to use preseed configuration
|
|
|
|
4. **Recreates ISO** (in Docker)
|
|
- Uses xorriso to create new hybrid ISO
|
|
- Supports both BIOS and UEFI boot
|
|
- Preserves all Debian installer features
|
|
|
|
5. **Verifies ISO** (in Docker)
|
|
- Checks ISO file exists
|
|
- Verifies file size and type
|
|
|
|
Output: `output/football-installer.iso`
|
|
|
|
### Step 3: Test ISO
|
|
|
|
Run `./scripts/test-iso.sh` which:
|
|
|
|
1. **Creates Test Disk** (in Docker)
|
|
- Creates 16GB QCOW2 disk for VM
|
|
- Used for testing installation
|
|
|
|
2. **Boots VM** (on host, using screen)
|
|
- Boots QEMU with 2GB RAM, 2 CPUs
|
|
- Uses `output/football-installer.iso` as boot device
|
|
- Creates 16GB test disk for installation
|
|
- Runs in background with screen session
|
|
- Saves console output to `output/vm-console.log`
|
|
|
|
3. **Monitors Installation**
|
|
- Waits 120 seconds for installer to start
|
|
- Checks for installation prompts
|
|
- Monitors for errors or kernel panic
|
|
|
|
Access VM console: `screen -r football-iso-test`
|
|
Detach from VM: `Ctrl+A`, then `D`
|
|
|
|
## Deployment
|
|
|
|
### Bare Metal Deployment
|
|
|
|
1. **Write ISO to USB**
|
|
```bash
|
|
sudo dd if=output/football-installer.iso of=/dev/sdX bs=4M status=progress
|
|
sync
|
|
```
|
|
|
|
2. **Boot from USB**
|
|
- Enter BIOS/UEFI
|
|
- Select USB as boot device
|
|
|
|
3. **Run Installer**
|
|
- Preseed auto-answers most questions
|
|
- Provide only:
|
|
- Username
|
|
- Password
|
|
- Root password
|
|
- Target disk
|
|
|
|
4. **Post-Install Configuration**
|
|
- Security configurations applied via preseed late_command
|
|
- WireGuard configured
|
|
- Firewall rules applied
|
|
- Services configured
|
|
|
|
### Virtual Machine Deployment
|
|
|
|
1. **Create VM Disk**
|
|
```bash
|
|
qemu-img create -f qcow2 football-disk.qcow2 16G
|
|
```
|
|
|
|
2. **Boot VM from ISO**
|
|
```bash
|
|
qemu-system-x86_64 \
|
|
-m 2048 \
|
|
-smp 2 \
|
|
-drive file=football-disk.qcow2,format=qcow2 \
|
|
-drive file=output/football-installer.iso,media=cdrom,readonly=on \
|
|
-boot d
|
|
```
|
|
|
|
3. **Run Installer**
|
|
- Same process as bare metal
|
|
|
|
## Docker Containers
|
|
|
|
### football-dev (Dockerfile.dev)
|
|
|
|
Fat development container with all build tools:
|
|
|
|
- `debootstrap` - Debian bootstrap tool
|
|
- `qemu-utils` - QEMU disk utilities
|
|
- `qemu-system-x86_64` - QEMU system emulator
|
|
- `grub-*` - GRUB bootloader tools
|
|
- `parted`, `fdisk`, `sfdisk` - Partitioning tools
|
|
- `xorriso` - ISO creation tool
|
|
- `wireguard` - WireGuard tools
|
|
- All other required build utilities
|
|
|
|
Usage:
|
|
```bash
|
|
docker build -t football-dev -f Dockerfile.dev .
|
|
docker run --rm -it -v "$PWD:/project" football-dev bash
|
|
```
|
|
|
|
### football-test (Dockerfile.test)
|
|
|
|
Lightweight test container for running tests:
|
|
|
|
- `bash` - Shell
|
|
- `shellcheck` - Shell script linting
|
|
- `shunit2` - Bash unit testing
|
|
- Basic utilities
|
|
|
|
Usage:
|
|
```bash
|
|
docker build -t football-test -f Dockerfile.test .
|
|
docker run --rm -v "$PWD:/test" football-test ./tests/verify-compliance.sh
|
|
```
|
|
|
|
## Security Features
|
|
|
|
Applied during installation via preseed:
|
|
|
|
1. **Network Isolation**
|
|
- All inbound traffic blocked
|
|
- WireGuard-only outbound traffic
|
|
- Mandatory VPN tunnel
|
|
|
|
2. **Service Restrictions**
|
|
- SSH disabled and masked
|
|
- All remote access services removed
|
|
- Bluetooth disabled
|
|
|
|
3. **System Hardening**
|
|
- Secure Boot enabled
|
|
- AppArmor enforcing
|
|
- Auditd logging enabled
|
|
- Fail2Ban configured
|
|
|
|
4. **Minimal Attack Surface**
|
|
- Only IceWM and Remmina installed
|
|
- No development tools
|
|
- Minimal command-line utilities
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Issues
|
|
|
|
**Problem**: ISO download fails
|
|
- **Solution**: Check network connectivity and Debian mirror availability
|
|
|
|
**Problem**: ISO creation fails
|
|
- **Solution**: Check xorriso installation in container
|
|
|
|
**Problem**: Preseed not working
|
|
- **Solution**: Check `config/preseed.cfg` syntax and boot command
|
|
|
|
### Test Issues
|
|
|
|
**Problem**: VM won't boot from ISO
|
|
- **Solution**: Check ISO file integrity and QEMU boot order
|
|
|
|
**Problem**: Installer not using preseed
|
|
- **Solution**: Check ISO boot command in `isolinux/isolinux.cfg`
|
|
|
|
**Problem**: Screen session issues
|
|
- **Solution**: Ensure screen is installed and properly configured
|
|
|
|
## Next Steps
|
|
|
|
After successful build and test:
|
|
|
|
1. **Deploy to target systems**
|
|
- Write ISO to USB
|
|
- Boot on bare metal or VM
|
|
- Complete installation with preseed
|
|
|
|
2. **Customize for environment**
|
|
- Update WireGuard configuration
|
|
- Add required packages
|
|
- Adjust security policies
|
|
|
|
3. **Verify compliance**
|
|
- Run `./tests/verify-compliance.sh`
|
|
- Run `./tests/compliance-test.sh`
|
|
- Document test results
|
|
|
|
## References
|
|
|
|
- [Debian Preseed Documentation](https://www.debian.org/releases/stable/amd64/apbs02.html.en)
|
|
- [CIS Debian Benchmark](https://www.cisecurity.org/benchmark/debian_linux)
|
|
- [WireGuard Documentation](https://www.wireguard.com/docs/)
|
|
- [Debian 13 (Trixie) Release Notes](https://www.debian.org/releases/trixie/releasenotes)
|