# 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)