mikkel/debate
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
debate/.planning/phases/01-core-infrastructure-security/01-05-SUMMARY.md
Mikkel Georgsen d2a038f562 docs(01-05): complete build sandbox plan 
Tasks completed: 3/3
- Create sandbox setup script and sandbox service
- Create deterministic build configuration service
- Create build orchestration service

SUMMARY: .planning/phases/01-core-infrastructure-security/01-05-SUMMARY.md
2026-01-25 20:22:17 +00:00

4.7 KiB
Raw Blame History

phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established duration completed
01-core-infrastructure-security 05 build
systemd-nspawn
sandbox
deterministic
archiso
iso-build
phase provides
01-01 FastAPI project structure, pydantic-settings configuration
phase provides
01-02 PostgreSQL database, Build model for tracking jobs
systemd-nspawn sandbox for isolated ISO builds
Deterministic build configuration with SOURCE_DATE_EPOCH
Build orchestration service with caching
02
03
04
added patterns
systemd-nspawn
archiso
sandbox-isolation
deterministic-builds
config-hash-caching
created modified
scripts/setup-sandbox.sh
backend/app/services/__init__.py
backend/app/services/sandbox.py
backend/app/services/deterministic.py
backend/app/services/build.py
tests/__init__.py
tests/test_deterministic.py
backend/app/core/config.py
Derive SOURCE_DATE_EPOCH from config hash, not wall clock (guarantees same config = same timestamp)
20 minute hard timeout with 15 minute warning for sandbox builds
Resource limits: 8GB RAM, 4 cores (generous for build speed per CONTEXT.md)
BuildSandbox pattern for isolated execution with systemd-nspawn
DeterministicBuildConfig for reproducible hash computation
BuildService orchestration with cache-first lookup
4min 2026-01-25

Phase 01 Plan 05: Build Sandbox & Deterministic Configuration Summary

systemd-nspawn sandbox with network isolation and deterministic build configuration using SOURCE_DATE_EPOCH derived from config hash

Performance

  • Duration: 4 min
  • Started: 2026-01-25T20:17:11Z
  • Completed: 2026-01-25T20:21:28Z
  • Tasks: 3
  • Files created: 7
  • Files modified: 1

Accomplishments

  • Created sandbox setup script for bootstrapping Arch base environment
  • Implemented BuildSandbox with network isolation (--private-network) and read-only root
  • Implemented DeterministicBuildConfig for reproducible ISO builds
  • Created BuildService for orchestrating build lifecycle with cache lookup
  • Added tests verifying hash determinism and order independence

Task Commits

Each task was committed atomically:

  1. Task 1: Create sandbox setup script and sandbox service - cd94d99 (feat)
  2. Task 2: Create deterministic build configuration service - c49aee7 (feat)
  3. Task 3: Create build orchestration service - c01b4cb (feat)

Files Created/Modified

  • scripts/setup-sandbox.sh - Bash script to bootstrap Arch base environment with pacstrap
  • backend/app/services/__init__.py - Services package exports
  • backend/app/services/sandbox.py - BuildSandbox class for systemd-nspawn container management
  • backend/app/services/deterministic.py - DeterministicBuildConfig for reproducible builds
  • backend/app/services/build.py - BuildService orchestration with cache-first lookup
  • backend/app/core/config.py - Added sandbox_root and iso_output_root settings
  • tests/__init__.py - Tests package
  • tests/test_deterministic.py - Tests for hash determinism and SOURCE_DATE_EPOCH

Decisions Made

  1. SOURCE_DATE_EPOCH derived from config hash - Instead of using wall clock time, the timestamp is computed from the first 16 hex chars of the config hash. This guarantees same configuration always produces same timestamp, enabling reproducible builds.

  2. 20 minute hard timeout - Per CONTEXT.md decision on build timeout handling, implemented 20 minute timeout (133% of 15 min target) with configurable warning at 15 minutes.

  3. Generous resource limits - Per CONTEXT.md "prioritize build speed over concurrent capacity", configured 8GB RAM and 4 cores for builds.

  4. Hash normalization - Config hashes sort packages and overlays, deduplicate packages, and hash file contents (not objects) to ensure order-independent determinism.

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

  • Ruff line length violation in profiledef.sh template string - fixed with bash line continuation
  • asyncio.TimeoutError deprecated in favor of builtin TimeoutError - updated per ruff UP041

User Setup Required

To use the sandbox, run (as root):

scripts/setup-sandbox.sh

This bootstraps an Arch Linux base environment at /var/lib/debate/sandbox/base.

Next Phase Readiness

  • Sandbox infrastructure ready for build worker implementation in Phase 3
  • Deterministic config hash enables caching strategy
  • BuildService provides interface for API endpoints in Phase 2

Phase: 01-core-infrastructure-security Completed: 2026-01-25