football/docs/BUILD-DOCUMENTATION.md

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

   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

   qemu-img create -f qcow2 football-disk.qcow2 16G
   

2. Boot VM from ISO

   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:

• 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:

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:

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
• CIS Debian Benchmark
• WireGuard Documentation
• Debian 13 (Trixie) Release Notes