Backup all current Debian-specific changes before reorganization

.forgejo/workflows/ci.yml

@@ -1,530 +0,0 @@
----
-name: Debian Forge CI/CD Pipeline
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main]
-  workflow_dispatch:
-
-env:
-  PYTHONPATH: "."
-  DEBIAN_FRONTEND: noninteractive
-
-jobs:
-  # Main build and test job
-  build-and-test:
-    name: Build and Test
-    runs-on: ubuntu-latest
-    container:
-      image: python:3.13-trixie
-
-    steps:
-      - name: Test secret priority
-        run: |
-          echo "Testing secret priority:"
-          echo "TEST_SECRET value: ${{ secrets.TEST_SECRET }}"
-          echo "User level: apple"
-          echo "Org level: pear"
-          echo "Repo level: pumpkin"
-
-          echo ""
-          echo "Available environment variables:"
-          echo "FORGEJO_RUN_NUMBER: ${FORGEJO_RUN_NUMBER:-'NOT_SET'}"
-          echo "GITEA_RUN_NUMBER: ${GITEA_RUN_NUMBER:-'NOT_SET'}"
-          echo "ACTIONS_RUN_NUMBER: ${ACTIONS_RUN_NUMBER:-'NOT_SET'}"
-          echo "GITHUB_RUN_NUMBER: ${GITHUB_RUN_NUMBER:-'NOT_SET'}"
-          echo "RUNNER_OS: ${RUNNER_OS:-'NOT_SET'}"
-          echo "GITEA_ACTOR: ${GITEA_ACTOR:-'NOT_SET'}"
-
-      - name: Setup environment
-        run: |
-          # Using Python 3.13-slim-trixie for modern Python + Debian Trixie packages
-          # Trixie provides modern OSTree packages with full features
-          # Bookworm (stable) has outdated OSTree packages missing critical functionality
-          # Try apt-cacher-ng first, fallback to Debian's automatic mirror selection
-          echo "Checking for apt-cacher-ng availability..."
-
-          # Quick check with timeout to avoid hanging
-          if timeout 10 curl -s --connect-timeout 5 http://192.168.1.101:3142/acng-report.html > /dev/null 2>&1; then
-            echo "✅ apt-cacher-ng is available, configuring proxy sources..."
-            echo "deb http://192.168.1.101:3142/ftp.debian.org/debian trixie main contrib non-free" > /etc/apt/sources.list
-            echo "deb-src http://192.168.1.101:3142/ftp.debian.org/debian trixie main contrib non-free" >> /etc/apt/sources.list
-            echo "Using apt-cacher-ng proxy for faster builds"
-          else
-            echo "⚠️ apt-cacher-ng not available or slow, using Debian's automatic mirror selection..."
-            echo "deb http://httpredir.debian.org/debian trixie main contrib non-free" > /etc/apt/sources.list
-            echo "deb-src http://deb.debian.org/debian trixie main contrib non-free" >> /etc/apt/sources.list
-            echo "Using httpredir.debian.org for automatic mirror selection"
-          fi
-
-          # APT Performance Optimizations (2-3x faster)
-          echo 'Acquire::Languages "none";' > /etc/apt/apt.conf.d/99translations
-          echo 'Acquire::GzipIndexes "true";' >> /etc/apt/apt.conf.d/99translations
-          echo 'Acquire::CompressionTypes::Order:: "gz";' >> /etc/apt/apt.conf.d/99translations
-          echo 'Dpkg::Use-Pty "0";' >> /etc/apt/apt.conf.d/99translations
-
-          # Update package lists
-          apt update -y
-
-      - name: Install dependencies
-        run: |
-          apt update -y
-          apt install -y --no-install-recommends \
-            git curl pkg-config build-essential gnupg wget \
-            python3-dev python3-pip python3-setuptools python3-wheel \
-            python3-venv python3-pytest python3-coverage \
-            devscripts debhelper dh-python python3-all python3-setuptools \
-            libapt-pkg-dev libapt-pkg7.0 libostree-dev \
-            libssl-dev libdbus-1-dev libglib2.0-dev \
-            libpolkit-gobject-1-dev libzstd-dev \
-            libcurl4-gnutls-dev libsystemd-dev libmount-dev \
-            libselinux1-dev libsepol-dev libarchive-dev \
-            libgpgme-dev libavahi-client-dev libavahi-common-dev \
-            libffi-dev libpcre2-dev libxml2-dev zlib1g-dev \
-            liblz4-dev liblzma-dev nettle-dev libgmp-dev \
-            libicu-dev \
-            crossbuild-essential-amd64 crossbuild-essential-arm64 \
-            gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
-            gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf \
-            lintian
-
-      - name: Checkout code
-        run: |
-          # Clone the repository manually
-          git clone https://git.raines.xyz/particle-os/debian-forge.git /tmp/debian-forge
-          cp -r /tmp/debian-forge/* .
-          cp -r /tmp/debian-forge/.* . 2>/dev/null || true
-
-      - name: Setup Python environment
-        run: |
-          # Python 3.13 is pre-installed in python:3.13-slim-trixie
-          echo "Python version: $(python3 --version)"
-          echo "Pip version: $(pip3 --version)"
-          
-          # Create virtual environment
-          python3 -m venv venv
-          # Use . instead of source for POSIX shell compatibility (dash in python:3.13-slim-trixie)
-          . venv/bin/activate
-
-          # Upgrade pip and install build tools
-          pip install --upgrade pip setuptools wheel
-
-          # Install Python dependencies
-          pip install -r requirements.txt
-
-          # Install development dependencies
-          pip install pytest pytest-cov black flake8 mypy
-
-          # Install additional build dependencies
-          pip install --upgrade setuptools wheel
-          
-          # Install missing runtime dependencies that might not be in requirements.txt
-          pip install mako jinja2 pyyaml license_expression
-
-      - name: Run tests
-        run: |
-          # Use . instead of source for POSIX shell compatibility (dash in python:3.13-slim-trixie)
-          . venv/bin/activate
-
-          # Create pytest configuration for CI environment
-          cat > pytest.ini << 'EOF'
-          [pytest]
-          # Allow up to 10 test failures (expected in CI environment)
-          maxfail = 10
-          # Short traceback format for CI logs
-          tb = short
-          # Mark tests that require root privileges
-          markers =
-              root: marks tests as requiring root privileges
-              slow: marks tests as slow
-          # Filter warnings to reduce noise
-          filterwarnings =
-              ignore::DeprecationWarning
-              ignore::PendingDeprecationWarning
-          EOF
-
-          # Run Python tests
-          # Note: Some tests are expected to fail in CI environment (permission-related, mount operations)
-          # We allow up to 10 failures to account for these expected CI limitations
-          echo "Running Python tests..."
-          
-          # Use external script to handle test execution and exit codes properly
-          ./scripts/run-tests-ci.sh
-
-          echo "✅ Tests completed (some expected failures in CI environment)"
-
-          # Provide test summary and explanation
-          echo ""
-          echo "📊 Test Results Summary:"
-          echo "================================"
-          echo "✅ Core functionality tests: PASSED"
-          echo "❌ Expected CI failures: 7 tests (permission-related, mount operations)"
-          echo "⏭️ Skipped tests: 190 (root-only, missing tools, etc.)"
-          echo ""
-          echo "📝 Expected Failures Explanation:"
-          echo "• Mount operations fail due to container permission limitations"
-          echo "• TOML write support not available in CI environment"
-          echo "• Export tests fail due to mount permission restrictions"
-          echo "• These failures are NORMAL and expected in CI environment"
-          echo "• All core osbuild functionality is working correctly"
-          echo ""
-          echo "🚀 Proceeding to package building stage..."
-
-      - name: Build Debian packages
-        run: |
-          echo "Building Debian packages using external script..."
-
-          # Run the external build script
-          ./scripts/build-debian-packages.sh
-
-      - name: Test built packages
-        run: |
-          echo "Testing built packages..."
-
-          # Find packages
-          DEB_PACKAGES=$(ls *.deb 2>/dev/null)
-          if [ -z "$DEB_PACKAGES" ]; then
-            DEB_PACKAGES=$(ls ../*.deb 2>/dev/null)
-            if [ -n "$DEB_PACKAGES" ]; then
-              cp ../*.deb .
-              DEB_PACKAGES=$(ls *.deb 2>/dev/null)
-            fi
-          fi
-
-          if [ -n "$DEB_PACKAGES" ]; then
-            echo "✅ Found packages: $DEB_PACKAGES"
-
-            # Test package installation (dry run)
-            echo "Testing package installation (dry run)..."
-            for pkg in *.deb; do
-              echo "Testing $pkg..."
-              dpkg-deb -I "$pkg" || echo "Package info test failed for $pkg"
-              dpkg-deb -c "$pkg" | head -10 || echo "Package contents test failed for $pkg"
-            done
-          else
-            echo "❌ No packages found to test"
-          fi
-
-      - name: Create build summary
-        run: |
-          echo "Creating build summary..."
-
-          # Create a summary markdown file
-          echo '# Debian Forge CI Summary' > CI_SUMMARY.md
-          echo '' >> CI_SUMMARY.md
-          echo '## Build Information' >> CI_SUMMARY.md
-          echo '- **Build Date**: '"$(date '+%Y-%m-%d %H:%M:%S UTC')" >> CI_SUMMARY.md
-          echo '- **Build ID**: '"$(date +%s)" >> CI_SUMMARY.md
-          echo '- **Commit**: '"$(git rev-parse --short HEAD 2>/dev/null || echo "Unknown")" >> CI_SUMMARY.md
-          echo '- **Branch**: '"$(git branch --show-current 2>/dev/null || echo "Unknown")" >> CI_SUMMARY.md
-          echo '' >> CI_SUMMARY.md
-          echo '## Build Status' >> CI_SUMMARY.md
-          echo '- **Status**: ✅ SUCCESS' >> CI_SUMMARY.md
-          echo '- **Container**: python:3.13-slim-trixie' >> CI_SUMMARY.md
-          echo '- **Python Version**: '"$(python3 --version)" >> CI_SUMMARY.md
-          echo '' >> CI_SUMMARY.md
-          echo '## Built Packages' >> CI_SUMMARY.md
-          echo '' >> CI_SUMMARY.md
-
-          # Add package information
-          if ls *.deb >/dev/null 2>&1; then
-            echo '### Debian Packages' >> CI_SUMMARY.md
-            for pkg in *.deb; do
-              PKG_NAME=$(dpkg-deb -f "$pkg" Package 2>/dev/null || echo "Unknown")
-              PKG_VERSION=$(dpkg-deb -f "$pkg" Version 2>/dev/null || echo "Unknown")
-              PKG_ARCH=$(dpkg-deb -f "$pkg" Architecture 2>/dev/null || echo "Unknown")
-              PKG_SIZE=$(du -h "$pkg" | cut -f1)
-              echo "- **$PKG_NAME** ($PKG_VERSION) [$PKG_ARCH] - $PKG_SIZE" >> CI_SUMMARY.md
-            done
-          fi
-
-          # Add sub-package information
-          echo '' >> CI_SUMMARY.md
-          echo '## Sub-Packages Included' >> CI_SUMMARY.md
-          echo '- **debian-forge** - Core engine and main binary' >> CI_SUMMARY.md
-          echo '- **python3-debian-forge** - Python library' >> CI_SUMMARY.md
-          echo '- **debian-forge-depsolve-deb** - Debian package dependency solver' >> CI_SUMMARY.md
-          echo '- **debian-forge-ostree** - OSTree support' >> CI_SUMMARY.md
-          echo '- **debian-forge-luks2** - LUKS2 encryption support' >> CI_SUMMARY.md
-          echo '- **debian-forge-lvm2** - LVM2 support' >> CI_SUMMARY.md
-          echo '- **debian-forge-selinux** - SELinux support' >> CI_SUMMARY.md
-          echo '- **debian-forge-apparmor** - AppArmor support (Debian preferred)' >> CI_SUMMARY.md
-          echo '- **debian-forge-tools** - Helper tools and utilities' >> CI_SUMMARY.md
-
-          echo "CI summary created: CI_SUMMARY.md"
-          echo "✅ All CI jobs completed successfully! 🎉"
-
-      - name: Prepare artifacts for upload
-        run: |
-          echo "Preparing artifacts for upload..."
-
-          # Create artifacts directory
-          mkdir -p artifacts
-
-          # Copy all built packages
-          if ls *.deb >/dev/null 2>&1; then
-            echo "📦 Copying Debian packages to artifacts directory..."
-            cp *.deb artifacts/
-            echo "✅ Packages copied:"
-            ls -la artifacts/*.deb
-
-            # Show package details
-            echo ""
-            echo "📋 Package Details:"
-            for pkg in artifacts/*.deb; do
-              PKG_NAME=$(dpkg-deb -f "$pkg" Package 2>/dev/null || echo "Unknown")
-              PKG_VERSION=$(dpkg-deb -f "$pkg" Version 2>/dev/null || echo "Unknown")
-              PKG_ARCH=$(dpkg-deb -f "$pkg" Architecture 2>/dev/null || echo "Unknown")
-              PKG_SIZE=$(du -h "$pkg" | cut -f1)
-              echo "  🎯 $PKG_NAME ($PKG_VERSION) [$PKG_ARCH] - $PKG_SIZE"
-            done
-          else
-            echo "❌ No .deb packages found"
-            exit 1
-          fi
-
-          # Copy build summary
-          if [ -f "CI_SUMMARY.md" ]; then
-            cp CI_SUMMARY.md artifacts/
-          fi
-
-          # Copy test coverage report
-          if [ -d "htmlcov" ]; then
-            cp -r htmlcov artifacts/
-          fi
-
-          echo "Artifacts prepared successfully!"
-          echo "Contents of artifacts directory:"
-          ls -la artifacts/
-
-      - name: Publish to Forgejo Debian Registry
-        run: |
-          echo "Publishing .deb packages to Forgejo Debian Registry..."
-
-          # Get build info for registry
-          BUILD_NUMBER="${FORGEJO_RUN_NUMBER:-${GITEA_RUN_NUMBER:-$(date +%Y%m%d%H%M%S)}}"
-          COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
-
-          echo "Publishing packages for build $BUILD_NUMBER (commit $COMMIT_HASH)"
-
-          # Forgejo Debian Registry configuration
-          FORGEJO_OWNER="particle-os"
-          FORGEJO_DISTRIBUTION="trixie"
-          FORGEJO_COMPONENT="main"
-
-          # Publish each .deb file
-          for deb_file in *.deb; do
-            echo "📦 Publishing $deb_file..."
-
-            # Extract package info
-            PKG_NAME=$(dpkg-deb -f "$deb_file" Package 2>/dev/null || echo "debian-forge")
-            PKG_VERSION=$(dpkg-deb -f "$deb_file" Version 2>/dev/null || echo "unknown")
-            PKG_ARCH=$(dpkg-deb -f "$deb_file" Architecture 2>/dev/null || echo "all")
-
-            echo "  Package: $PKG_NAME"
-            echo "  Version: $PKG_VERSION"
-            echo "  Architecture: $PKG_ARCH"
-
-            # Forgejo Debian Registry upload URL
-            UPLOAD_URL="https://git.raines.xyz/api/packages/${FORGEJO_OWNER}/debian/pool/${FORGEJO_DISTRIBUTION}/${FORGEJO_COMPONENT}/upload"
-
-            # Upload to Forgejo Debian Registry
-            if [ -n "${{ secrets.ACCESS_TOKEN }}" ]; then
-              echo "  🔐 Using authentication token..."
-              UPLOAD_RESULT=$(curl -s -w "%{http_code}" \
-                --user "${FORGEJO_OWNER}:${{ secrets.ACCESS_TOKEN }}" \
-                --upload-file "$deb_file" \
-                "$UPLOAD_URL" 2>/dev/null)
-
-              HTTP_CODE=$(echo "$UPLOAD_RESULT" | tail -c 4)
-              RESPONSE_BODY=$(echo "$UPLOAD_RESULT" | head -c -4)
-
-              case $HTTP_CODE in
-                201)
-                  echo "  ✅ Successfully published to Forgejo Debian Registry!"
-                  echo "  📥 Install with: apt install $PKG_NAME"
-                  ;;
-                409)
-                  echo "  ⚠️ Package already exists (version conflict)"
-                  ;;
-                400)
-                  echo "  ❌ Bad request - package validation failed"
-                  ;;
-                *)
-                  echo "  ❌ Upload failed with HTTP $HTTP_CODE"
-                  echo "  Response: $RESPONSE_BODY"
-                  ;;
-              esac
-            else
-              echo "  ⚠️ No ACCESS_TOKEN secret available - skipping upload"
-            fi
-
-            echo ""
-          done
-
-          echo "🎯 Debian package publishing complete!"
-          echo "📦 Packages are now available in Forgejo Debian Registry"
-          echo "🔧 To install: apt install debian-forge"
-
-  # Security check
-  security:
-    name: Security Audit
-    runs-on: ubuntu-latest
-    container:
-      image: python:3.13-slim-trixie
-
-    steps:
-      - name: Setup environment
-        run: |
-          # Configure sources
-          echo "deb http://httpredir.debian.org/debian trixie main contrib non-free" > /etc/apt/sources.list
-          apt update -y
-
-      - name: Install security tools
-        run: |
-          apt install -y --no-install-recommends git python3-pip bandit safety
-
-      - name: Checkout code
-        run: |
-          git clone https://git.raines.xyz/particle-os/debian-forge.git /tmp/debian-forge
-          cp -r /tmp/debian-forge/* .
-          cp -r /tmp/debian-forge/.* . 2>/dev/null || true
-
-      - name: Run security audit
-        run: |
-          # Install dependencies
-          pip install -r requirements.txt
-
-          # Run bandit security scan
-          echo "Running bandit security scan..."
-          bandit -r osbuild/ -f json -o bandit-report.json || echo "Bandit found issues (this is normal)"
-
-          # Run safety check
-          echo "Running safety check..."
-          safety check || echo "Safety check completed (warnings are normal)"
-
-          echo "✅ Security audit completed! 🛡️"
-
-  # Package validation
-  package:
-    name: Package Validation
-    runs-on: ubuntu-latest
-    container:
-      image: python:3.13-slim-trixie
-
-    steps:
-      - name: Setup environment
-        run: |
-          echo "deb http://httpredir.debian.org/debian trixie main contrib non-free" > /etc/apt/sources.list
-          apt update -y
-
-      - name: Install package tools
-        run: |
-          apt install -y --no-install-recommends \
-            git devscripts debhelper dh-python python3-all lintian
-
-      - name: Checkout code
-        run: |
-          git clone https://git.raines.xyz/particle-os/debian-forge.git /tmp/debian-forge
-          cp -r /tmp/debian-forge/* .
-          cp -r /tmp/debian-forge/.* . 2>/dev/null || true
-
-      - name: Validate package structure
-        run: |
-          echo "Validating package structure..."
-
-          # Check for required files
-          [ -f "setup.py" ] && echo "✅ setup.py found" || echo "❌ setup.py missing"
-          [ -f "setup.cfg" ] && echo "✅ setup.cfg found" || echo "❌ setup.cfg missing"
-          [ -d "osbuild" ] && echo "✅ osbuild/ directory found" || echo "❌ osbuild/ directory missing"
-          [ -d "stages" ] && echo "✅ stages/ directory found" || echo "❌ stages/ directory missing"
-
-          # Check Debian packaging files
-          if [ -d "debian" ]; then
-            [ -f "debian/control" ] && echo "✅ debian/control found" || echo "❌ debian/control missing"
-            [ -f "debian/rules" ] && echo "✅ debian/rules found" || echo "❌ debian/rules missing"
-            [ -f "debian/copyright" ] && echo "✅ debian/copyright found" || echo "❌ debian/copyright missing"
-            [ -f "debian/changelog" ] && echo "✅ debian/changelog found" || echo "❌ debian/changelog missing"
-            [ -f "debian/compat" ] && echo "✅ debian/compat found" || echo "❌ debian/compat missing"
-          fi
-
-          echo "Package validation completed!"
-
-      - name: Run lintian quality checks
-        run: |
-          echo "Running lintian quality checks..."
-
-          if [ -d "debian" ]; then
-            echo "Checking Debian packaging quality..."
-
-            if command -v lintian >/dev/null 2>&1; then
-              echo "✅ Lintian found, running quality checks..."
-              lintian --allow-root --no-tag-display-limit debian/ || echo "Lintian found issues (this is normal for development)"
-              echo "Lintian quality checks completed!"
-            else
-              echo "⚠️ Lintian not available, skipping quality checks"
-            fi
-          else
-            echo "❌ No debian directory found for lintian checks"
-          fi
-
-      - name: Create package summary
-        run: |
-          echo "Package validation completed!"
-          echo "✅ Package check completed! 📦"
-
-  # Final status report
-  status:
-    name: Status Report
-    runs-on: ubuntu-latest
-    container:
-      image: python:3.13-slim-trixie
-    needs: [build-and-test, security, package]
-
-    steps:
-      - name: Setup environment
-        run: |
-          echo "deb http://httpredir.debian.org/debian trixie main contrib non-free" > /etc/apt/sources.list
-          apt update -y
-          apt install -y --no-install-recommends git
-
-      - name: Checkout code
-        run: |
-          git clone https://git.raines.xyz/particle-os/debian-forge.git /tmp/debian-forge
-          cp -r /tmp/debian-forge/* .
-          cp -r /tmp/debian-forge/.* . 2>/dev/null || true
-
-      - name: Create status report
-        run: |
-          echo "# Debian Forge CI Status Report" > STATUS_REPORT.md
-          echo "" >> STATUS_REPORT.md
-          echo "## Summary" >> STATUS_REPORT.md
-          echo "- **Build and Test**: ✅ Completed" >> STATUS_REPORT.md
-          echo "- **Security Audit**: ✅ Completed" >> STATUS_REPORT.md
-          echo "- **Package Validation**: ✅ Completed" >> STATUS_REPORT.md
-          echo "- **Sub-Package Support**: ✅ All 8 packages built" >> STATUS_REPORT.md
-          echo "- **Quality Checks**: ✅ Lintian validation completed" >> STATUS_REPORT.md
-          echo "" >> STATUS_REPORT.md
-          echo "## Details" >> STATUS_REPORT.md
-          echo "- **Commit**: $(git rev-parse --short HEAD 2>/dev/null || echo 'Unknown')" >> STATUS_REPORT.md
-          echo "- **Branch**: $(git branch --show-current 2>/dev/null || echo 'Unknown')" >> STATUS_REPORT.md
-          echo "- **Date**: $(date '+%Y-%m-%d %H:%M:%S UTC')" >> STATUS_REPORT.md
-          echo "- **Container**: python:3.13-slim-trixie" >> STATUS_REPORT.md
-          echo "" >> STATUS_REPORT.md
-          echo "All CI jobs completed successfully! 🎉" >> STATUS_REPORT.md
-          echo "" >> STATUS_REPORT.md
-          echo "## Sub-Packages Built" >> STATUS_REPORT.md
-          echo "- **debian-forge** - Core engine and main binary" >> STATUS_REPORT.md
-          echo "- **python3-debian-forge** - Python library" >> STATUS_REPORT.md
-          echo "- **debian-forge-depsolve-deb** - Debian package dependency solver" >> STATUS_REPORT.md
-          echo "- **debian-forge-ostree** - OSTree support" >> STATUS_REPORT.md
-          echo "- **debian-forge-luks2** - LUKS2 encryption support" >> STATUS_REPORT.md
-          echo "- **debian-forge-lvm2** - LVM2 support" >> STATUS_REPORT.md
-          echo "- **debian-forge-selinux** - SELinux support" >> STATUS_REPORT.md
-          echo "- **debian-forge-apparmor** - AppArmor support (Debian preferred)" >> STATUS_REPORT.md
-          echo "- **debian-forge-tools** - Helper tools and utilities" >> STATUS_REPORT.md
-
-          echo "Status report created: STATUS_REPORT.md"
-          echo "✅ All CI jobs completed successfully!"

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence.
+*               @osbuild/osbuild-reviewers
+
+# SBOM
+/osbuild/util/sbom/     @thozza
+
+# Depsolving
+/osbuild/solver/        @thozza
+/tools/solver*.json     @thozza
+/tools/**/*depsolve*    @thozza
+
+# image-info tool
+/tools/**/*osbuild*image*info*  @thozza

.github/mergify.yml

@@ -0,0 +1,24 @@
+
+pull_request_rules:
+  - name: Automatic review for Dependabot pull requests
+    conditions:
+      - author~=^dependabot(|-preview)\[bot\]$
+      - title~=^Bump [^\s]+ from ([\d]+)\..+ to \1\.
+      - "#changes-requested-reviews-by=0"
+      - base=main
+    actions:
+      review:
+        type: APPROVE
+        message: Automatically approving dependabot (minor version bump)
+      label:
+        add:
+          - ci:automerge
+
+  - name: Dismiss reviews for non trusted authors
+    conditions:
+      - base=main
+      - author!=@Schutzbot
+    actions:
+      dismiss_reviews:
+        approved: True
+        changes_requested: True

.github/workflows/check.yml

@@ -0,0 +1,92 @@
+name: Checks
+
+on: [pull_request, push]
+
+permissions:
+  contents: read
+
+jobs:
+  spelling_checker:
+    name: "Spelling"
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codespell-project/actions-codespell@master
+        with:
+          ignore_words_list: msdos, pullrequest
+          skip: ./.git,coverity,rpmbuild,samples
+
+  python_code_linters:
+      name: "Python Linters"
+      runs-on: ubuntu-24.04
+      steps:
+      - name: "Clone Repository"
+        uses: actions/checkout@v4
+      - name: "Run Linters"
+        uses: osbuild/containers/src/actions/privdocker@552e30cf1b4ed19c6ddaa57f96c342b3dff4227b
+        with:
+          image: ghcr.io/osbuild/osbuild-ci:latest-202502250751
+          run: |
+            make lint
+
+  shell_linters:
+    name: "Shell Linters"
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: "Clone Repository"
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: "Differential ShellCheck"
+      uses: redhat-plumbers-in-action/differential-shellcheck@v3
+      with:
+        severity: warning
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+  packit-config-lint:
+    name: "📦 Packit config lint"
+    runs-on: ubuntu-24.04
+    container:
+      image: registry.fedoraproject.org/fedora:latest
+    steps:
+      - name: Install Packit
+        run: dnf -y install packit
+
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Validate Packit config
+        run: |
+          packit config validate .packit.yaml
+
+  snapshots:
+    name: "🔍 Check for valid snapshot urls"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Check for valid snapshot urls
+        run: ./tools/check-snapshots --errors-only .
+
+  json-fmt:
+    name: "🔍 Check JSON files for formatting consistency"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Install utils
+        run: |
+          sudo apt update
+          sudo apt install -y jq moreutils
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Reformat all json files
+        run: find -iname "*.json" -print -exec sh -c 'jq --indent 2 . {} | sponge {}' \;
+      - name: Check diff
+        run: git diff --exit-code

.github/workflows/coverity.yml

@@ -0,0 +1,40 @@
+name: Coverity
+on:
+  schedule:
+    - cron: '0 5 * * *' # Daily at 05:00 UTC
+
+jobs:
+  coverity:
+    name: "Test Suite"
+    if: github.repository == 'osbuild/osbuild'
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: osbuild
+    steps:
+
+      - name: Clone repository
+        uses: actions/checkout@v4
+        with:
+          path: osbuild
+
+      - name: Install Dependencies
+        run: |
+          sudo apt-get install python3-setuptools
+
+      - name: Download Coverity Tool
+        run: |
+          make coverity-download
+        env:
+         COVERITY_TOKEN: ${{ secrets.COVERITY_TOKEN }}
+
+      - name: Coverity check
+        run: |
+          make coverity-check
+
+      - name: Upload analysis results
+        run: |
+          make coverity-submit
+        env:
+         COVERITY_TOKEN: ${{ secrets.COVERITY_TOKEN }}
+         COVERITY_EMAIL: ${{ secrets.COVERITY_EMAIL }}

.github/workflows/create-tag.yml

@@ -0,0 +1,30 @@
+# This action creates a release every second Wednesday
+name: "Create and push release tag"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to tag. Useful for making the first "dot" release from a rhel-x.y branch.'
+        required: false
+        default: ""
+  schedule:
+    - cron: "0 8 * * 3"
+
+jobs:
+  tag-and-push:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Even or odd week
+        run: if [ `expr \`date +\%s\` / 86400 \% 2` -eq 0 ]; then echo "WEEK=odd" >> $GITHUB_ENV; else echo "WEEK=even" >> $GITHUB_ENV; fi
+        shell: bash
+
+      - name: Upstream tag
+        uses: osbuild/release-action@create-tag
+        if: ${{ env.WEEK == 'even' || github.event_name != 'schedule' }}
+        with:
+          token: "${{ secrets.SCHUTZBOT_GITHUB_ACCESS_TOKEN }}"
+          username: "imagebuilder-bot"
+          email: "imagebuilder-bots+imagebuilder-bot@redhat.com"
+          version: ${{ github.event.inputs.version }}

.github/workflows/generate.yml

@@ -0,0 +1,55 @@
+name: Generate
+
+on: [pull_request, push]
+
+jobs:
+  generate_documentation:
+    name: "Documentation"
+    runs-on: ubuntu-24.04
+    container:
+      image: docker.io/library/python:3.7
+    steps:
+      - name: Install Dependencies
+        run: |
+          pip install docutils
+
+      - name: Clone repository
+        uses: actions/checkout@v4
+        with:
+          path: osbuild
+
+      - name: Generate Documentation
+        run: |
+          make \
+            -f osbuild/Makefile \
+            SRCDIR=osbuild \
+            BUILDDIR=build \
+            RST2MAN=rst2man.py \
+            man
+
+      - name: Verify Documentation
+        working-directory: build
+        run: |
+          test -d docs
+          test -f docs/osbuild.1
+
+  generate_test_data:
+    name: "Test Data"
+    runs-on: ubuntu-24.04
+    env:
+      OSBUILD_MPP_CACHEDIR: "/var/tmp/osbuild-mpp-cache"
+    steps:
+    - name: "Clone Repository"
+      uses: actions/checkout@v4
+    - name: Cache metadata
+      uses: actions/cache@v4
+      with:
+        path: /var/tmp/osbuild-mpp-cache
+        key: no-key-needed-here
+    - name: "Regenerate Test Data"
+      uses: osbuild/containers/src/actions/privdocker@552e30cf1b4ed19c6ddaa57f96c342b3dff4227b
+      with:
+        image: ghcr.io/osbuild/osbuild-ci:latest-202502250751
+        run: |
+          make test-data
+          git diff --exit-code -- ./test/data

.github/workflows/pr_best_practices.yml

@@ -0,0 +1,18 @@
+name: "Verify PR best practices"
+
+on:
+  pull_request_target:
+    branches: [main]
+    types: [opened, synchronize, reopened, edited]
+  issue_comment:
+    types: [created]
+
+jobs:
+  pr-best-practices:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: PR best practice check
+        uses: osbuild/pr-best-practices@main
+        with:
+          token: ${{ secrets.SCHUTZBOT_GITHUB_ACCESS_TOKEN }}
+          jira_token: ${{ secrets.IMAGEBUILDER_BOT_JIRA_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: "Create GitHub release"
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Upstream release
+        uses: osbuild/release-action@main
+        with:
+          token: "${{ secrets.SCHUTZBOT_GITHUB_ACCESS_TOKEN }}"
+          slack_webhook_url: "${{ secrets.SLACK_WEBHOOK_URL }}"

.github/workflows/stale-cleanup.yml

@@ -0,0 +1,17 @@
+name: Mark and close stale issues and PRs
+
+on:
+  schedule:
+    - cron: '0 4 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-24.04
+    permissions:
+      actions: write  # needed to clean up the saved action state
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: osbuild/common-stale-action@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-on-centos.yml

@@ -0,0 +1,34 @@
+name: Run tests in Centos container
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 1 * * *'
+
+jobs:
+  tests-on-centos:
+    strategy:
+      matrix:
+        centos:
+          - version: "9"
+            pytest_exclude: 'not (TestBoot and boot)'
+          - version: "10"
+            pytest_exclude: 'not (TestBoot and boot) and not (test_write_read)'
+    name: "Unittests on Centos Stream ${{ matrix.centos.version }}"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+      - name: "Run in container"
+        uses: addnab/docker-run-action@v3
+        with:
+          image: quay.io/osbuild/osbuild-ci-c${{ matrix.centos.version }}s:latest-202502250751
+          options: --privileged -v ${{ github.workspace }}:/osbuild --workdir /osbuild
+          run: |
+            python3 -m pytest \
+            --rootdir $(pwd) \
+            --ignore $(pwd)/test/src \
+            --unsupported-fs btrfs \
+            -k "${{ matrix.centos.pytest_exclude }}" \
+            -v \
+            $(pwd)/test/

.github/workflows/test.yml

@@ -0,0 +1,95 @@
+name: Tests
+
+on: [pull_request, push]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Share the store between the workers speeds things up further
+  OSBUILD_TEST_STORE: /var/tmp/osbuild-test-store
+
+jobs:
+  test_suite:
+    name: "Unittest"
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        test:
+          - parallel
+          - normal
+        environment:
+          - "py36"    # RH8
+          - "py39"    # RH9
+          - "py313"   # latest stable Fedora
+          - "py314"   # Fedora rawhide
+    steps:
+    - name: "Clone Repository"
+      uses: actions/checkout@v4
+    - name: "Run"
+      uses: osbuild/containers/src/actions/privdocker@552e30cf1b4ed19c6ddaa57f96c342b3dff4227b
+      with:
+        image: ghcr.io/osbuild/osbuild-ci:latest-202506112350
+        run: |
+          # Hacky replacement of container storage driver:
+          # The default overlayfs doesn't work in the runner, so let's change
+          # it to vfs for the local storage skopeo stage test.
+          sed -i 's/overlay/vfs/g' /usr/share/containers/storage.conf  # default system config
+          sed -i 's/overlay/vfs/g' /etc/containers/storage.conf || true  # potential overrides
+          if [ "${{ matrix.test }}" == "parallel" ]; then
+              # 4 is a bit arbitrary
+              TEST_WORKERS="-n 4"
+              TEST_CATEGORY="test_stages.py"
+          else
+              # test_assemblers.py is run below
+              TEST_CATEGORY="not test_stages.py and not test_assemblers.py"
+
+              # DNF python package can't be installed using pip in the tox environment.
+              # We need to use the version from the system to test things.
+              # Since we are running tests on Fedora, enable site packages only
+              # for Python version which is available on Fedora.
+              # See also: https://github.com/osbuild/containers/pull/79
+              if [ "${{ matrix.environment }}" == "$(cat /osb/libdnf-python-version)" ]; then
+                  TOX_ARGS="-x testenv.sitepackages=True"
+              fi
+          fi
+          OSBUILD_TEST_STORE="${{ env.OSBUILD_TEST_STORE }}" \
+          tox -e "${{ matrix.environment }}" $TOX_ARGS -- -rs $TEST_WORKERS -k "$TEST_CATEGORY"
+
+  v1_manifests:
+    name: "Assembler test (legacy)"
+    runs-on: ubuntu-24.04
+    steps:
+      - name: "Clone Repository"
+        uses: actions/checkout@v4
+      - name: "Run"
+        uses: osbuild/containers/src/actions/privdocker@552e30cf1b4ed19c6ddaa57f96c342b3dff4227b
+        env:
+          # Using 4 workers is a bit arbitrary, "auto" is probably too aggressive.
+          TEST_WORKERS: "-n 4"
+        with:
+          image: ghcr.io/osbuild/osbuild-ci:latest-202506112350
+          run: |
+            OSBUILD_TEST_STORE="${{ env.OSBUILD_TEST_STORE }}" \
+            tox -e "py36" -- ${{ env.TEST_WORKERS }} test.run.test_assemblers
+
+  # This smoke test runs the unit tests directly on the runner and as a
+  # normal user - it is fast (2min) and should detect obvious issues
+  # (like from pr#1942)
+  unittests_as_user_smoke:
+    name: "Smoke run: unittest as normal user on default runner"
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      # The test_host.py:test_signals_on_separate_fd runs itself but that
+      # run will happen without the tox env so a pip/tox installed pytest
+      # will not be found, install the pytest package as a workaround
+    - run: sudo apt install -y tox python3-pytest
+    - name: "Run as user on default runer"
+      # Run with -n 16 as depsolve tests tend to be slow but fast when
+      # parallized, the runtime is around 1-2min with this setup.
+      run: |
+        tox -e py312 -- -n 16

.github/workflows/trigger-gitlab.yml

@@ -0,0 +1,63 @@
+# inspired by rhinstaller/anaconda
+
+name: Trigger GitLab CI
+
+on:
+  workflow_run:
+    workflows: ["Checks"]
+    types: [completed]
+
+jobs:
+  trigger-gitlab:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-24.04
+    env:
+      IMAGEBUILDER_BOT_GITLAB_SSH_KEY: ${{ secrets.IMAGEBUILDER_BOT_GITLAB_SSH_KEY }}
+    steps:
+      - name: Report status
+        uses: haya14busa/action-workflow_run-status@v1
+
+      - name: Install Dependencies
+        run: |
+          sudo apt install -y jq
+
+      - name: Clone repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - uses: octokit/request-action@v2.x
+        id: fetch_pulls
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          route: GET /repos/${{ github.repository }}/pulls
+
+      - name: Checkout branch
+        env:
+          BRANCH: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          PR_DATA=$(mktemp)
+          # use uuid as a file terminator to avoid conflicts with data content
+          cat > "$PR_DATA" <<'a21b3e7f-d5eb-44a3-8be0-c2412851d2e6'
+          ${{ steps.fetch_pulls.outputs.data }}
+          a21b3e7f-d5eb-44a3-8be0-c2412851d2e6
+
+          PR=$(jq -rc '.[] | select(.head.sha | contains("${{ github.event.workflow_run.head_sha }}")) | select(.state | contains("open"))' "$PR_DATA" | jq -r .number)
+          if [ ! -z "$PR" ]; then
+            git checkout -b PR-$PR
+          else
+            git checkout "${BRANCH}"
+          fi
+
+      - name: Push to gitlab
+        run: |
+          mkdir -p ~/.ssh
+          echo "${IMAGEBUILDER_BOT_GITLAB_SSH_KEY}" > ~/.ssh/id_rsa
+          chmod 400 ~/.ssh/id_rsa
+          touch ~/.ssh/known_hosts
+          ssh-keyscan -t rsa gitlab.com >> ~/.ssh/known_hosts
+          git remote add ci git@gitlab.com:redhat/services/products/image-builder/ci/osbuild.git
+          git push -f ci
+          git push -f --tags ci

.github/workflows/update-images.yml

@@ -0,0 +1,52 @@
+# This action updates the images ref in the Schutzfile
+---
+    name: "Update images ref"
+    
+    on:
+      workflow_dispatch:
+      schedule:
+        # Every Mon at 8:00
+        - cron: "0 8 * * 1"
+    
+    jobs:
+      update-and-push:
+        runs-on: ubuntu-24.04
+        steps:
+          - name: Apt update
+            run: sudo apt update
+    
+          - name: Check out main
+            uses: actions/checkout@v4
+            with:
+              path: osbuild
+              ref: main
+    
+          - name: Update Schutzfile
+            working-directory: ./osbuild
+            env:
+              GITHUB_TOKEN: ${{ secrets.SCHUTZBOT_GITHUB_ACCESS_TOKEN }}
+            run: |
+              ./schutzbot/update-schutzfile-images
+    
+          - name: Open PR
+            working-directory: ./osbuild
+            env:
+              GITHUB_TOKEN: ${{ secrets.SCHUTZBOT_GITHUB_ACCESS_TOKEN }}
+            run: |
+              if git diff --exit-code; then echo "No changes"; exit 0; fi
+              git config --unset-all http.https://github.com/.extraheader
+              git config user.name "schutzbot"
+              git config user.email "schutzbot@gmail.com"
+              branch="schutzfile-images-$(date -I)"
+              git checkout -b "${branch}"
+              git add Schutzfile
+              git commit -m "Schutzfile: Update images dependency ref to latest"
+              git push -f https://"$GITHUB_TOKEN"@github.com/schutzbot/osbuild.git
+              echo "Updating images dependency ref to current \`main\`" > body
+              gh pr create \
+                -t "Update images dependency ref to latest" \
+                -F "body" \
+                -r "osbuild/osbuild-reviewers" \
+                --repo "osbuild/osbuild" \
+                --base "main" \
+                --head "schutzbot:${branch}"

.gitignore

@@ -1,4 +1,3 @@
-# OSBuild specific ignores
 *.tar.gz
 *.egg-info
 __pycache__
@@ -11,6 +10,9 @@ __pycache__
 /.idea
 /.gdb_history
 
+/build-logs
+/cache
+
 cov-analysis-linux64/
 cov-analysis-osbuild.xz
 cov-int/
@@ -29,187 +31,3 @@ venv
 
 debian-forge-docs/debos
 debian-forge-docs/koji
-
-# Embedded git repositories
-docs/debian/debos/
-docs/debian/koji/
-
-# Python bytecode and cache files
-*.pyc
-*.pyo
-*.pyd
-*.so
-*.dylib
-*.dll
-*.exe
-*.bin
-
-# Python package files (but allow test data)
-*.egg
-*.whl
-*.tar
-*.zip
-*.gz
-*.bz2
-*.xz
-*.7z
-!test/**/*.tar
-!test/**/*.gz
-!test/**/*.xml
-!test/**/*.html
-!test/**/*.css
-!test/**/*.js
-!docs/**/*.xml
-!docs/**/*.html
-!docs/**/*.css
-!docs/**/*.js
-
-# Build directories
-build/
-dist/
-*.deb
-
-# Debian build artifacts
-debian/
-debian-*/
-*.buildinfo
-*.changes
-*.dsc
-*.tar.xz
-*.tar.gz
-
-# CI/CD artifacts
-artifacts/
-build-logs/
-build-environments/
-*.tar.gz
-*.zip
-
-# Test and coverage files
-test-output/
-coverage/
-.coverage
-*.cover
-htmlcov/
-.pytest_cache/
-
-# Temporary and backup files
-*.tmp
-*.temp
-*.log
-*.pid
-*.lock
-*.bak
-*.backup
-*.orig
-*.rej
-*.patch
-*.diff
-*~
-!test/**/*.log
-!docs/**/*.log
-
-# System files
-Thumbs.db
-.Trash*
-.nfs*
-
-# IDE and editor files
-*.swp
-*.swo
-.vimrc
-.emacs
-.sublime-*
-.project
-.classpath
-.settings
-
-# OS-specific files
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-
-# Lock files (but allow test data)
-*.lock
-.cache.lock
-!test/**/*.lock
-
-# Cache directories
-.cache/
-cache/
-
-# Environment files
-.env
-.env.local
-.env.*.local
-
-# Local configuration files (collaborator-specific)
-config/*.local.conf
-config/*.local.*
-*.local.conf
-*.local.*
-
-# Backup files
-*.bak
-*.old
-*.save
-
-# Temporary build artifacts
-tmp/
-temp/
-
-# OSBuild stage files (but allow test data)
-assemblers/org.osbuild.tar
-stages/org.osbuild.rpm
-stages/org.osbuild.tar
-stages/org.osbuild.xz
-stages/org.osbuild.zip
-
-# Cloud and container image artifacts
-*.qcow2
-*.vmdk
-*.vhd
-*.vdi
-*.iso
-*.img
-*.raw
-*.ova
-*.ovf
-
-# Docker and OCI artifacts
-*.docker
-*.oci
-docker-images/
-oci-images/
-
-# Cloud provider artifacts
-aws-output/
-gcp-output/
-azure-output/
-cloud-output/
-live-iso-output/
-pxe-output/
-
-# Debug and profiling artifacts
-debug-reports/
-*.debug
-*.profile
-*.trace
-/tmp/debian-forge-*
-/tmp/cloud-output/
-/tmp/container-output/
-/tmp/live-iso-output/
-
-# Performance test artifacts
-performance-results/
-comprehensive-results/
-error-handling-results/
-
-# Mock integration artifacts (when implemented)
-mock-environments/
-mock-cache/
-mock-logs/

README.md

@@ -1,234 +1,131 @@
-# Debian Forge
+# ~~OSBuild~~ Debian Forge
 
-A Debian-specific fork of OSBuild with comprehensive APT package management support for building Debian and Ubuntu images.
+A fork of osbuild, but for debian.
+Try to be as close as 1:1 os possible
 
-## Features
+Build-Pipelines for Operating System Artifacts
 
-### 🚀 **Complete APT Support**
-- **`org.osbuild.apt`** - Full APT package installation with dependency resolution
-- **`org.osbuild.apt.config`** - APT configuration and repository management
-- **`org.osbuild.debootstrap`** - Base Debian filesystem creation
-- **`org.osbuild.debian.source`** - Source package management
+OSBuild is a pipeline-based build system for operating system artifacts. It
+defines a universal pipeline description and a build system to execute them,
+producing artifacts like operating system images, working towards an image
+build pipeline that is more comprehensible, reproducible, and extendable.
 
-### 🎯 **Cross-Distribution Support**
-- **Debian** - Trixie, Bookworm, Sid support
-- **Ubuntu** - Jammy, Focal, and other LTS releases
-- **Cross-Architecture** - amd64, arm64, and more
+See the `osbuild(1)` man-page for details on how to run osbuild, the definition
+of the pipeline description, and more.
 
-### ⚡ **Performance Optimized**
-- **APT Caching** - 2-3x faster builds with apt-cacher-ng
-- **Parallel Builds** - Multi-architecture support
-- **Minimal Images** - Optimized base images
+## Project
 
-### 🔧 **Production Ready**
-- **CI/CD Integration** - Automated build pipelines
-- **Comprehensive Testing** - Full test coverage
-- **Documentation** - Complete user guides and examples
+ * **Website**: https://www.osbuild.org
+ * **Bug Tracker**: https://github.com/osbuild/osbuild/issues
+ * **Discussions**: https://github.com/orgs/osbuild/discussions
+ * **Matrix**: #image-builder on [fedoraproject.org](https://matrix.to/#/#image-builder:fedoraproject.org)
+ * **Changelog**: https://github.com/osbuild/osbuild/releases
 
-## Quick Start
+### Principles
 
-### Installation
+1. [OSBuild stages](./stages) are never broken, only deprecated. The same manifest should always produce the same output.
+2. [OSBuild stages](./stages) should be explicit whenever possible instead of e.g. relying on the state of the tree.
+3. Pipelines are independent, so the tree is expected to be empty at the beginning of each.
+4. Manifests are expected to be machine-generated, so OSBuild has no convenience functions to support manually created manifests.
+5. The build environment is confined against accidental misuse, but this should not be considered a security boundary.
+6. OSBuild may only use Python language features supported by the oldest target distribution.
 
-```bash
-# Clone the repository
-git clone https://git.raines.xyz/particle-os/debian-forge.git
-cd debian-forge
+### Contributing
 
-# Install dependencies
-sudo apt install python3-dev python3-pip python3-venv
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
+Please refer to the [developer guide](https://osbuild.org/docs/developer-guide/index) to learn about our workflow, code style and more.
+
+## Requirements
+
+The requirements for this project are:
+
+ * `bubblewrap >= 0.4.0`
+ * `python >= 3.6`
+
+Additionally, the built-in stages require:
+
+ * `bash >= 5.0`
+ * `coreutils >= 8.31`
+ * `curl >= 7.68`
+ * `qemu-img >= 4.2.0`
+ * `debootstrap >= 1.0.0`
+ * `mmdebstrap >= 1.0.0`
+ * `tar >= 1.32`
+ * `util-linux >= 235`
+ * `skopeo`
+ * `ostree >= 2023.1`
+
+At build-time, the following software is required:
+
+ * `python-docutils >= 0.13`
+ * `pkg-config >= 0.29`
+
+Testing requires additional software:
+
+ * `pytest`
+
+## Running locally
+
+The main binary is safe to run on your development machine with:
+
+    python3 -m osbuild --libdir .
+
+To build an image:
+
+    python3 -m osbuild --libdir . ./test-debian-manifest.json
+
+Every osbuild run uses a cache for downloaded files (sources) and, optionally,
+checkpoints of artifacts built by stages and pipelines. By default, this is
+kept in `.osbuild` (in the current working directory). The location of this
+directory can be specified using the `--cache` option.
+
+For more information about the options and arguments, read [man pages](/docs).
+
+## Build
+
+Osbuild is a python script so it is not compiled.
+To verify changes made to the code use included makefile rules:
+
+ * `make lint` to run linter on top of the code
+ * `make test-all` to run base set of tests
+ * `sudo make test-run` to run extended set of tests (takes long time)
+
+Also keep in mind that some tests require those prerequisites,
+otherwise they are skipped
+
+```
+sudo apt install -y debootstrap mmdebstrap sbuild schroot ostree qemu-utils
 ```
 
-### Basic Usage
+## Installation
 
-Create a simple Debian image:
+Installing `osbuild` requires to not only install the `osbuild` module, but also
+additional artifacts such as tools (i.e: `osbuild-mpp`) sources, stages, schemas
+and SELinux policies.
 
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64"
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": ["linux-image-amd64", "systemd", "openssh-server"]
-          }
-        }
-      ]
-    }
-  ]
-}
+For this reason, doing an installation from source is not trivial and the easier
+way to install it is to create the set of Debian packages that contain all these components.
+
+This can be done with the `deb` make target, i.e:
+
+```sh
+sudo apt builddep osbuild.spec
+make deb
 ```
 
-Build the image:
+A set of Debian packages will be created in the `./debbuild/` directory and can
+be installed in the system using the distribution package manager, i.e:
 
-```bash
-python3 -m osbuild manifest.json --output-dir ./output --libdir .
+```sh
+sudo apt install ./debbuild/*.deb
 ```
 
-## Examples
+## Repository
 
-### Debian Trixie Minimal
-```bash
-python3 -m osbuild test/data/manifests/debian/debian-trixie-minimal.json --libdir .
-```
-
-### Ubuntu Jammy Server
-```bash
-python3 -m osbuild test/data/manifests/debian/ubuntu-jammy-server.json --libdir .
-```
-
-### ARM64 Cross-Architecture
-```bash
-python3 -m osbuild test/data/manifests/debian/debian-trixie-arm64.json --libdir .
-```
-
-## Documentation
-
-- [APT Stages Reference](docs/apt-stages.md) - Complete API documentation
-- [Debian Image Building Tutorial](docs/debian-image-building-tutorial.md) - Step-by-step guide
-- [Performance Optimization](docs/performance-optimization.md) - Speed up your builds
-- [Example Manifests](test/data/manifests/debian/) - Real-world examples
-
-## APT Stages
-
-### `org.osbuild.debootstrap`
-Creates base Debian filesystem using debootstrap.
-
-**Options:**
-- `suite` - Debian suite (trixie, jammy, etc.)
-- `mirror` - Debian mirror URL
-- `arch` - Target architecture
-- `variant` - Debootstrap variant (minbase, buildd)
-- `extra_packages` - Additional packages to include
-
-### `org.osbuild.apt`
-Installs Debian packages using APT.
-
-**Options:**
-- `packages` - List of packages to install
-- `recommends` - Install recommended packages
-- `update` - Update package lists
-- `apt_proxy` - APT proxy URL
-
-### `org.osbuild.apt.config`
-Configures APT settings and repositories.
-
-**Options:**
-- `sources` - Repository configuration
-- `preferences` - Package preferences and pinning
-- `apt_proxy` - APT proxy URL
-
-## Performance
-
-### With apt-cacher-ng
-- **2-3x faster builds** for repeated packages
-- **Reduced bandwidth** usage
-- **Offline capability** for cached packages
-
-### Build Times
-| Image Type | Base Time | With Cache | Improvement |
-|------------|-----------|------------|-------------|
-| Minimal Debian | 5-10 min | 2-3 min | 60-70% |
-| Server Image | 10-15 min | 4-6 min | 60-70% |
-| Ubuntu Image | 8-12 min | 3-5 min | 60-70% |
-
-## CI/CD Integration
-
-### Forgejo Workflow
-```yaml
-name: Build and Test
-on: [push, pull_request]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    container: python:3.13-slim-trixie
-    steps:
-      - uses: actions/checkout@v4
-      - name: Build Debian packages
-        run: ./scripts/build-debian-packages.sh
-```
-
-### Package Building
-```bash
-# Build all packages
-./scripts/build-debian-packages.sh
-
-# Test packages
-dpkg-deb -I *.deb
-```
-
-## Comparison with Upstream OSBuild
-
-| Feature | OSBuild | Debian Forge |
-|---------|---------|--------------|
-| **Package Manager** | RPM/DNF | APT |
-| **Distributions** | Fedora/RHEL | Debian/Ubuntu |
-| **Base Creation** | dnf/rpm | debootstrap |
-| **Dependency Resolution** | DNF | APT |
-| **Repository Management** | YUM repos | sources.list |
-| **Cross-Architecture** | x86_64, aarch64 | amd64, arm64, etc. |
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
-
-### Development Setup
-```bash
-# Install development dependencies
-pip install -r requirements-dev.txt
-
-# Run tests
-python3 -m pytest test/
-
-# Run linting
-flake8 osbuild/
-```
+ - **web**:   https://github.com/osbuild/osbuild
+ - **https**: `https://github.com/osbuild/osbuild.git`
+ - **ssh**:   `git@github.com:osbuild/osbuild.git`
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgments
-
-- **OSBuild** - The original project that inspired this fork
-- **Debian Project** - For the excellent package management system
-- **Ubuntu** - For the LTS releases and community support
-
-## Support
-
-- **Documentation** - [docs/](docs/)
-- **Issues** - [GitLab Issues](https://git.raines.xyz/particle-os/debian-forge/-/issues)
-- **Discussions** - [GitLab Discussions](https://git.raines.xyz/particle-os/debian-forge/-/discussions)
-
-## Roadmap
-
-- [x] **Phase 1-5** - Project structure and packaging
-- [x] **Phase 6** - APT implementation (COMPLETE!)
-- [x] **Phase 7.1** - Documentation and examples
-- [ ] **Phase 7.2** - Performance optimization
-- [ ] **Phase 7.3** - Advanced features
-- [ ] **Phase 8** - Cloud image generation
-- [ ] **Phase 9** - Container image building
-- [ ] **Phase 10** - Live ISO creation
-
----
-
-**Debian Forge** - Building Debian and Ubuntu images with the power of OSBuild! 🚀
+ - **Apache-2.0**
+ - See LICENSE file for details.

artifacts/metadata/debian-manifest.json

@@ -0,0 +1,43 @@
+{
+  "version": "2",
+  "pipelines": [
+    {
+      "name": "debian-base",
+      "build": "name:debian-base",
+      "stages": [
+        {
+          "name": "org.osbuild.debootstrap",
+          "options": {
+            "suite": "bookworm",
+            "mirror": "http://deb.debian.org/debian",
+            "arch": "amd64",
+            "variant": "minbase",
+            "apt_proxy": "http://192.168.1.101:3142"
+          }
+        },
+        {
+          "name": "org.osbuild.apt",
+          "options": {
+            "packages": ["systemd", "systemd-sysv", "dbus", "udev"],
+            "recommends": false,
+            "update": true,
+            "apt_proxy": "http://192.168.1.101:3142"
+          }
+        },
+        {
+          "name": "org.osbuild.ostree.commit",
+          "options": {
+            "repository": "debian-atomic",
+            "branch": "debian/bookworm",
+            "subject": "Debian Bookworm base system",
+            "metadata": {
+              "version": "12",
+              "variant": "minbase",
+              "arch": "amd64"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

blueprints/debian-atomic-container.json

@@ -0,0 +1,109 @@
+{
+  "name": "debian-atomic-container",
+  "description": "Debian Atomic Container Host",
+  "version": "1.0.0",
+  "distro": "debian-bookworm",
+  "arch": "amd64",
+  "packages": [
+    {
+      "name": "libsystemd0"
+    },
+    {
+      "name": "libc6"
+    },
+    {
+      "name": "systemd"
+    },
+    {
+      "name": "systemd-sysv"
+    },
+    {
+      "name": "libdbus-1-3"
+    },
+    {
+      "name": "dbus"
+    },
+    {
+      "name": "libudev1"
+    },
+    {
+      "name": "udev"
+    },
+    {
+      "name": "libostree-1-1"
+    },
+    {
+      "name": "libglib2.0-0"
+    },
+    {
+      "name": "ostree"
+    },
+    {
+      "name": "linux-image-6.1.0-13-amd64"
+    },
+    {
+      "name": "linux-firmware"
+    },
+    {
+      "name": "linux-image-amd64"
+    },
+    {
+      "name": "podman"
+    },
+    {
+      "name": "buildah"
+    },
+    {
+      "name": "skopeo"
+    },
+    {
+      "name": "containers-common"
+    },
+    {
+      "name": "crun"
+    }
+  ],
+  "modules": [],
+  "groups": [],
+  "customizations": {
+    "user": [
+      {
+        "name": "debian",
+        "description": "Debian atomic user",
+        "password": "$6$rounds=656000$debian$atomic.system.user",
+        "home": "/home/debian",
+        "shell": "/bin/bash",
+        "groups": [
+          "wheel",
+          "sudo"
+        ],
+        "uid": 1000,
+        "gid": 1000
+      }
+    ],
+    "services": {
+      "enabled": [
+        "sshd",
+        "systemd-networkd",
+        "systemd-resolved",
+        "podman"
+      ],
+      "disabled": [
+        "systemd-timesyncd"
+      ]
+    },
+    "kernel": {
+      "append": "ostree=/ostree/boot.1/debian/bookworm/0"
+    },
+    "filesystem": {
+      "/var/lib/containers": {
+        "type": "directory",
+        "mode": "0755"
+      }
+    }
+  },
+  "ostree": {
+    "ref": "debian/bookworm/container",
+    "parent": "debian/bookworm/base"
+  }
+}

build-logs/build-000001.log

@@ -0,0 +1,6 @@
+2025-08-22T18:43:44.007228 - Build build-000001: Build submitted - Priority: 5
+2025-08-22T18:43:44.008134 - Build build-000001: Build submitted - Priority: 5
+2025-08-22T18:43:45.009838 - Build build-000001: Build submitted - Priority: 5
+2025-08-22T20:45:25.433439 - Build build-000001: Build submitted - Priority: 5
+2025-08-22T20:45:45.179487 - Build build-000001: Build submitted - Priority: 5
+2025-08-22T20:45:55.222544 - Build build-000001: Build submitted - Priority: 5

build-logs/build-000002.log

@@ -0,0 +1,3 @@
+2025-08-22T18:43:44.007550 - Build build-000002: Build submitted - Priority: 3
+2025-08-22T18:43:44.008287 - Build build-000002: Build submitted - Priority: 3
+2025-08-22T18:43:45.010066 - Build build-000002: Build submitted - Priority: 4

build-logs/build-000003.log

@@ -0,0 +1,2 @@
+2025-08-22T18:43:44.007774 - Build build-000003: Build submitted - Priority: 7
+2025-08-22T18:43:45.010198 - Build build-000003: Build submitted - Priority: 3

build-logs/build-000004.log

@@ -0,0 +1 @@
+2025-08-22T18:43:45.010403 - Build build-000004: Build submitted - Priority: 2

build-logs/build-000005.log

@@ -0,0 +1 @@
+2025-08-22T18:43:45.010639 - Build build-000005: Build submitted - Priority: 1

cache/metadata/last_sync.json

@@ -0,0 +1,5 @@
+{
+  "repository": "http://deb.debian.org/debian",
+  "suite": "bookworm",
+  "last_sync": "2025-08-23T11:03:24.790058"
+}

config/README.md

@@ -1,184 +0,0 @@
-# Debian Forge Configuration
-
-This directory contains configuration files for Debian Forge. The system is designed to be collaborative-friendly, allowing each developer to have their own settings without affecting others.
-
-## Configuration Files
-
-### `debian-forge.conf` (Default Configuration)
-- **Purpose**: Default configuration values for the project
-- **Status**: Tracked in git (shared by all collaborators)
-- **Usage**: Contains sensible defaults and examples
-
-### `debian-forge.local.conf.example` (Template)
-- **Purpose**: Template for local configuration
-- **Status**: Tracked in git (shared template)
-- **Usage**: Copy this file to create your local configuration
-
-### `debian-forge.local.conf` (Local Configuration)
-- **Purpose**: Your personal configuration settings
-- **Status**: **NOT tracked in git** (personal to each collaborator)
-- **Usage**: Customize this file for your environment
-
-## Quick Start
-
-### 1. Set up your local configuration
-```bash
-# Create your local configuration file
-./tools/debian-forge-config setup
-
-# This copies the example template to config/debian-forge.local.conf
-# Edit this file to customize your settings
-```
-
-### 2. Configure apt-cacher-ng proxy
-```bash
-# Set your proxy URL
-./tools/debian-forge-config apt-proxy http://localhost:3142
-
-# Or disable proxy
-./tools/debian-forge-config apt-proxy none
-
-# Or set via environment variable
-export DEBIAN_FORGE_APT_PROXY=http://localhost:3142
-```
-
-### 3. View current configuration
-```bash
-./tools/debian-forge-config show
-```
-
-## Configuration Options
-
-### apt-cacher-ng Section
-```ini
-[apt-cacher-ng]
-# Set to your proxy URL, or leave empty to disable
-url = http://localhost:3142
-```
-
-**Examples:**
-- `url = http://localhost:3142` - Local proxy
-- `url = http://192.168.1.100:3142` - Network proxy
-- `url = http://apt-cache.company.local:3142` - Company proxy
-- `url = ` - No proxy (leave empty)
-
-### build Section
-```ini
-[build]
-# We support Debian 13+ (Trixie and newer)
-# Current Debian releases:
-# - trixie (Debian 13) - STABLE (recommended)
-# - forky (Debian 14) - TESTING
-# - sid (Debian Unstable) - UNSTABLE (use with caution)
-default_suite = trixie
-default_arch = amd64
-timeout = 3600
-jobs = 4
-```
-
-**Debian Release Status (as of 2024):**
-- **trixie** (Debian 13) - **STABLE** - Recommended for production
-- **forky** (Debian 14) - **TESTING** - For development and testing
-- **sid** (Debian Unstable) - **UNSTABLE** - Use with caution
-- **bookworm** (Debian 12) - **OLDSTABLE** - Limited support
-- **bullseye** (Debian 11) - **OLDOLDSTABLE** - Not supported
-
-**Note**: Debian Forge supports **Debian 13+ (Trixie and newer)**. Older releases may have compatibility issues.
-
-### stages Section
-```ini
-[stages]
-apt_update = true
-apt_recommends = false
-apt_unauthenticated = false
-```
-
-## Priority Order
-
-Configuration values are loaded in this priority order (highest to lowest):
-
-1. **Stage options** (passed directly to stages)
-2. **Environment variables** (e.g., `DEBIAN_FORGE_APT_PROXY`)
-3. **Local configuration** (`debian-forge.local.conf`)
-4. **Default configuration** (`debian-forge.conf`)
-
-## Environment Variables
-
-You can override any configuration setting using environment variables:
-
-```bash
-# Override apt-cacher-ng proxy
-export DEBIAN_FORGE_APT_PROXY=http://localhost:3142
-
-# Override default suite
-export DEBIAN_FORGE_DEFAULT_SUITE=forky
-
-# Override default architecture
-export DEBIAN_FORGE_DEFAULT_ARCH=arm64
-```
-
-## CLI Tool Usage
-
-The `debian-forge-config` tool provides several commands:
-
-```bash
-# Set up local configuration
-./tools/debian-forge-config setup
-
-# Show current configuration
-./tools/debian-forge-config show
-
-# Set apt-cacher-ng proxy
-./tools/debian-forge-config apt-proxy http://localhost:3142
-
-# Set any configuration value
-./tools/debian-forge-config set build default_suite trixie
-```
-
-## Collaboration Workflow
-
-### For New Collaborators:
-1. Clone the repository
-2. Run `./tools/debian-forge-config setup`
-3. Edit `config/debian-forge.local.conf` with your settings
-4. Your local settings won't affect others
-
-### For Existing Collaborators:
-1. Your `debian-forge.local.conf` is already configured
-2. Update settings as needed using the CLI tool
-3. Your changes remain local
-
-### For Project Updates:
-1. Default configuration changes are tracked in git
-2. Your local overrides are preserved
-3. You can merge new default settings as needed
-
-## File Locations
-
-- **Default config**: `config/debian-forge.conf`
-- **Your local config**: `config/debian-forge.local.conf` (create this)
-- **Template**: `config/debian-forge.local.conf.example`
-- **CLI tool**: `tools/debian-forge-config`
-
-## Troubleshooting
-
-### Configuration not loading?
-- Check that `config/debian-forge.local.conf` exists
-- Verify file permissions
-- Use `./tools/debian-forge-config show` to debug
-
-### Proxy not working?
-- Verify your proxy URL is correct
-- Check that apt-cacher-ng is running
-- Use environment variable override for testing
-
-### Settings not taking effect?
-- Remember the priority order
-- Stage options override configuration files
-- Use `./tools/debian-forge-config show` to see current values
-
-### Debian version compatibility?
-- We support Debian 13+ (Trixie and newer)
-- Older releases may have compatibility issues
-- Use `trixie` (stable) for production builds
-- Use `forky` (testing) for development

config/build-system/build-environments.json

@@ -0,0 +1,40 @@
+{
+  "environments": [
+    {
+      "name": "bookworm-amd64",
+      "suite": "bookworm",
+      "architecture": "amd64",
+      "mirror": "http://deb.debian.org/debian",
+      "components": [
+        "main",
+        "contrib",
+        "non-free-firmware"
+      ],
+      "extra_repositories": [],
+      "build_dependencies": [
+        "build-essential",
+        "devscripts",
+        "debhelper"
+      ],
+      "enabled": true
+    },
+    {
+      "name": "sid-amd64",
+      "suite": "sid",
+      "architecture": "amd64",
+      "mirror": "http://deb.debian.org/debian",
+      "components": [
+        "main",
+        "contrib",
+        "non-free-firmware"
+      ],
+      "extra_repositories": [],
+      "build_dependencies": [
+        "build-essential",
+        "devscripts",
+        "debhelper"
+      ],
+      "enabled": true
+    }
+  ]
+}

config/debian-forge.conf

@@ -1,47 +0,0 @@
-# Debian Forge Configuration File
-# This file contains configuration options that can be customized per environment
-# Copy this file to config/debian-forge.local.conf and modify as needed
-# The .local.conf file is ignored by git, so each collaborator can have their own settings
-
-[apt-cacher-ng]
-# apt-cacher-ng proxy configuration
-# Set to empty string or comment out to disable
-# Examples:
-# url = http://localhost:3142
-# url = http://192.168.1.100:3142
-# url = http://apt-cache.company.local:3142
-# url = 
-
-# Alternative: use environment variable
-# Set DEBIAN_FORGE_APT_PROXY environment variable to override this setting
-# export DEBIAN_FORGE_APT_PROXY=http://localhost:3142
-
-[build]
-# Build environment settings
-# Default Debian suite to use
-# We support Debian 13+ (Trixie and newer)
-# Current Debian releases:
-# - trixie (Debian 13) - STABLE (recommended)
-# - forky (Debian 14) - TESTING
-# - sid (Debian Unstable) - UNSTABLE (use with caution)
-default_suite = trixie
-
-# Default architecture
-default_arch = amd64
-
-# Build timeout (in seconds)
-timeout = 3600
-
-# Parallel build jobs
-jobs = 4
-
-[stages]
-# Stage-specific settings
-apt_update = true
-apt_recommends = false
-apt_unauthenticated = false
-
-[logging]
-# Logging configuration
-level = INFO
-file = .osbuild/debian-forge.log

config/variants/flavors.json

@@ -0,0 +1,99 @@
+{
+  "flavors": [
+    {
+      "name": "gnome",
+      "display_name": "GNOME",
+      "description": "Modern, intuitive desktop environment",
+      "packages": [
+        "task-gnome-desktop",
+        "gnome-core"
+      ],
+      "dependencies": [
+        "gnome-session",
+        "gnome-shell",
+        "gdm3"
+      ],
+      "variants": [
+        "bookworm",
+        "sid",
+        "testing"
+      ],
+      "enabled": true,
+      "priority": 100
+    },
+    {
+      "name": "kde",
+      "display_name": "KDE Plasma",
+      "description": "Feature-rich, customizable desktop",
+      "packages": [
+        "task-kde-desktop",
+        "plasma-desktop"
+      ],
+      "dependencies": [
+        "kde-plasma-desktop",
+        "sddm"
+      ],
+      "variants": [
+        "bookworm",
+        "sid",
+        "testing"
+      ],
+      "enabled": true,
+      "priority": 200
+    },
+    {
+      "name": "xfce",
+      "display_name": "Xfce",
+      "description": "Lightweight, fast desktop environment",
+      "packages": [
+        "task-xfce-desktop",
+        "xfce4"
+      ],
+      "dependencies": [
+        "xfce4-session",
+        "lightdm"
+      ],
+      "variants": [
+        "bookworm",
+        "sid",
+        "testing"
+      ],
+      "enabled": true,
+      "priority": 300
+    },
+    {
+      "name": "mate",
+      "display_name": "MATE",
+      "description": "Traditional GNOME 2 desktop",
+      "packages": [
+        "task-mate-desktop",
+        "mate-desktop"
+      ],
+      "dependencies": [
+        "mate-session-manager",
+        "lightdm"
+      ],
+      "variants": [
+        "bookworm",
+        "sid",
+        "testing"
+      ],
+      "enabled": true,
+      "priority": 400
+    },
+    {
+      "name": "minimal",
+      "display_name": "Minimal",
+      "description": "Minimal system without desktop",
+      "packages": [],
+      "dependencies": [],
+      "variants": [
+        "bookworm",
+        "sid",
+        "testing"
+      ],
+      "enabled": true,
+      "priority": 500
+    }
+  ]
+}

config/variants/variants.json

@@ -0,0 +1,80 @@
+{
+  "variants": [
+    {
+      "name": "bookworm",
+      "codename": "Bookworm",
+      "version": "12",
+      "status": "stable",
+      "release_date": "2023-06-10T00:00:00",
+      "end_of_life": "2026-06-10T00:00:00",
+      "architectures": [
+        "amd64",
+        "arm64",
+        "armel",
+        "armhf",
+        "i386",
+        "mips64el",
+        "mipsel",
+        "ppc64el",
+        "s390x"
+      ],
+      "mirrors": [
+        "http://deb.debian.org/debian",
+        "http://security.debian.org/debian-security"
+      ],
+      "security_support": true,
+      "updates_support": true,
+      "backports_support": true
+    },
+    {
+      "name": "sid",
+      "codename": "Sid",
+      "version": "unstable",
+      "status": "unstable",
+      "release_date": null,
+      "end_of_life": null,
+      "architectures": [
+        "amd64",
+        "arm64",
+        "armel",
+        "armhf",
+        "i386",
+        "mips64el",
+        "mipsel",
+        "ppc64el",
+        "s390x"
+      ],
+      "mirrors": [
+        "http://deb.debian.org/debian"
+      ],
+      "security_support": false,
+      "updates_support": false,
+      "backports_support": false
+    },
+    {
+      "name": "testing",
+      "codename": "Trixie",
+      "version": "13",
+      "status": "testing",
+      "release_date": null,
+      "end_of_life": null,
+      "architectures": [
+        "amd64",
+        "arm64",
+        "armel",
+        "armhf",
+        "i386",
+        "mips64el",
+        "mipsel",
+        "ppc64el",
+        "s390x"
+      ],
+      "mirrors": [
+        "http://deb.debian.org/debian"
+      ],
+      "security_support": false,
+      "updates_support": false,
+      "backports_support": false
+    }
+  ]
+}

docs/apt-solver-implementation.md

@@ -1,284 +0,0 @@
-# APT Solver Implementation for debian-forge
-
-## 🎯 **Overview**
-
-The APT solver is a critical component of `debian-forge` that provides native Debian package management capabilities. Unlike the upstream `osbuild` project which only supports DNF/DNF5 solvers for RPM-based systems, `debian-forge` includes a comprehensive APT solver specifically designed for Debian and Ubuntu systems.
-
-## 🏗️ **Architecture**
-
-### **Solver Interface**
-The APT solver implements the standard `osbuild.solver.Solver` interface, providing:
-
-- **`dump()`** - Export current package state and configuration
-- **`depsolve()`** - Resolve package dependencies and conflicts
-- **`search()`** - Search for packages by name or description
-- **`get_package_info()`** - Get detailed package information
-- **`get_dependencies()`** - Get package dependency information
-
-### **Key Features**
-
-#### **1. Repository Management**
-- Support for multiple APT repositories
-- GPG key validation and management
-- Repository priority configuration
-- Component and architecture filtering
-- Proxy support for enterprise environments
-
-#### **2. Package Resolution**
-- Advanced dependency resolution
-- Conflict detection and resolution
-- Package exclusion support
-- Version pinning and holds
-- Clean dependency removal
-
-#### **3. Search Capabilities**
-- Package name search
-- Description-based search
-- Configurable result limits
-- Architecture-specific filtering
-
-#### **4. Configuration Management**
-- Root directory support for chroot environments
-- Custom APT configuration options
-- Environment variable handling
-- Proxy configuration
-
-## 📁 **File Structure**
-
-```
-osbuild/solver/
-├── __init__.py          # Solver interface and imports
-├── apt.py              # APT solver implementation
-├── dnf.py              # DNF solver (upstream)
-└── dnf5.py             # DNF5 solver (upstream)
-```
-
-## 🔧 **Implementation Details**
-
-### **APT Solver Class**
-
-```python
-class APT(SolverBase):
-    def __init__(self, request, persistdir, cache_dir, license_index_path=None):
-        # Initialize APT configuration
-        # Set up repositories
-        # Configure proxy settings
-        
-    def dump(self):
-        # Export package state and configuration
-        
-    def depsolve(self, arguments):
-        # Resolve package dependencies
-        
-    def search(self, args):
-        # Search for packages
-        
-    def get_package_info(self, package_name):
-        # Get detailed package information
-        
-    def get_dependencies(self, package_name):
-        # Get package dependencies
-```
-
-### **Configuration Options**
-
-#### **Repository Configuration**
-```python
-repos = [
-    {
-        "name": "debian-main",
-        "baseurl": "http://deb.debian.org/debian",
-        "enabled": True,
-        "gpgcheck": True,
-        "gpgkey": ["http://deb.debian.org/debian-archive-keyring.gpg"],
-        "priority": 500,
-        "components": ["main", "contrib", "non-free"],
-        "architectures": ["amd64", "arm64"],
-    }
-]
-```
-
-#### **APT Configuration**
-```python
-apt_config = {
-    "APT::Architecture": "amd64",
-    "APT::Default-Release": "trixie",
-    "APT::Get::Assume-Yes": "true",
-    "APT::Get::AllowUnauthenticated": "false",
-    "APT::Get::Fix-Broken": "true",
-    "APT::Install-Recommends": "false",
-    "APT::Install-Suggests": "false",
-}
-```
-
-## 🧪 **Testing**
-
-### **Test Suite**
-The APT solver includes comprehensive test coverage:
-
-- **`test/test_apt_solver.py`** - Basic functionality tests
-- **`test/test_apt_solver_real.py`** - Real-world system tests
-
-### **Test Categories**
-
-#### **1. Basic Functionality**
-- Solver initialization
-- Configuration validation
-- Repository management
-- Error handling
-
-#### **2. Real-World Testing**
-- System integration tests
-- Chroot environment tests
-- Advanced feature validation
-
-#### **3. Error Handling**
-- No repository scenarios
-- Invalid configuration handling
-- Network error simulation
-- Permission error handling
-
-## 🚀 **Usage Examples**
-
-### **Basic Package Resolution**
-```python
-from osbuild.solver.apt import APT
-
-request = {
-    "arch": "amd64",
-    "releasever": "trixie",
-    "arguments": {
-        "repos": [{"name": "debian", "baseurl": "http://deb.debian.org/debian"}],
-        "root_dir": "/path/to/chroot"
-    }
-}
-
-solver = APT(request, "/tmp", "/tmp")
-packages = solver.depsolve({"packages": ["apt", "curl"]})
-```
-
-### **Package Search**
-```python
-results = solver.search({
-    "query": "python3",
-    "match_type": "name",
-    "limit": 10
-})
-```
-
-### **Package Information**
-```python
-info = solver.get_package_info("apt")
-deps = solver.get_dependencies("apt")
-```
-
-## 🔄 **Integration with debian-forge**
-
-### **Stage Integration**
-The APT solver integrates seamlessly with `debian-forge` stages:
-
-- **`org.osbuild.apt`** - Uses APT solver for package installation
-- **`org.osbuild.apt.depsolve`** - Leverages solver for dependency resolution
-- **`org.osbuild.apt.mock`** - Integrates with mock environments
-
-### **Manifest Support**
-```json
-{
-  "pipeline": {
-    "build": {
-      "dependencies": {
-        "packages": ["apt", "curl", "python3"],
-        "repositories": [
-          {
-            "name": "debian-main",
-            "baseurl": "http://deb.debian.org/debian",
-            "gpgkey": ["http://deb.debian.org/debian-archive-keyring.gpg"]
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-## 🎯 **Advantages Over Upstream**
-
-### **1. Native Debian Support**
-- **Upstream**: Only DNF/DNF5 for RPM-based systems
-- **debian-forge**: Full APT support for Debian/Ubuntu
-
-### **2. Advanced Features**
-- Package pinning and holds
-- Repository priorities
-- GPG key management
-- Proxy support
-
-### **3. Debian-Specific Optimizations**
-- Optimized for Debian package management
-- Support for Debian-specific repository structures
-- Integration with Debian security updates
-
-### **4. Production Ready**
-- Comprehensive error handling
-- Extensive test coverage
-- Real-world validation
-- Performance optimization
-
-## 📊 **Performance Characteristics**
-
-### **Dependency Resolution**
-- **Speed**: Comparable to native APT
-- **Memory**: Optimized for large package sets
-- **Caching**: Intelligent package list caching
-
-### **Search Performance**
-- **Index-based**: Fast package name searches
-- **Description**: Full-text search capabilities
-- **Filtering**: Architecture and component filtering
-
-## 🔧 **Configuration Best Practices**
-
-### **1. Repository Configuration**
-- Use official Debian repositories
-- Enable GPG verification
-- Set appropriate priorities
-- Include security updates
-
-### **2. Performance Optimization**
-- Enable package list caching
-- Use local mirrors when possible
-- Configure appropriate timeouts
-- Set up proxy caching
-
-### **3. Security Considerations**
-- Always verify GPG keys
-- Use HTTPS repositories
-- Enable package verification
-- Regular security updates
-
-## 🚀 **Future Enhancements**
-
-### **Planned Features**
-- **APT preferences support** - Package version preferences
-- **Snap package support** - Integration with snap packages
-- **Flatpak support** - Flatpak application management
-- **Container integration** - Docker/OCI image support
-
-### **Performance Improvements**
-- **Parallel downloads** - Concurrent package downloads
-- **Delta updates** - Efficient package updates
-- **Compression** - Optimized package storage
-- **Caching** - Advanced caching strategies
-
-## 📚 **Documentation References**
-
-- [APT Solver API Reference](apt-solver-api.md)
-- [Repository Configuration Guide](repository-configuration.md)
-- [Performance Tuning Guide](performance-tuning.md)
-- [Troubleshooting Guide](troubleshooting.md)
-
-## 🎉 **Conclusion**
-
-The APT solver implementation represents a significant advancement for `debian-forge`, providing native Debian package management capabilities that are not available in the upstream `osbuild` project. With comprehensive testing, extensive documentation, and production-ready features, the APT solver enables `debian-forge` to be a true Debian-native image building solution.
-
-**Status: PRODUCTION READY** 🚀

docs/apt-stages.md

@@ -1,209 +0,0 @@
-# APT Stages for Debian Forge
-
-This document describes the APT-related stages available in `debian-forge`, which provide comprehensive Debian/Ubuntu package management support.
-
-## Available Stages
-
-### 1. `org.osbuild.debootstrap`
-
-Creates a base Debian filesystem using `debootstrap`, similar to how OSBuild uses `dnf` for Fedora.
-
-**Options:**
-- `suite` (string, required): Debian suite to bootstrap (e.g., "trixie", "jammy", "sid")
-- `mirror` (string, required): Debian mirror URL
-- `arch` (string, optional): Target architecture (e.g., "amd64", "arm64")
-- `variant` (string, optional): Debootstrap variant (e.g., "minbase", "buildd")
-- `extra_packages` (array, optional): Additional packages to include in base filesystem
-- `apt_proxy` (string, optional): apt-cacher-ng proxy URL
-
-**Example:**
-```json
-{
-  "type": "org.osbuild.debootstrap",
-  "options": {
-    "suite": "trixie",
-    "mirror": "http://deb.debian.org/debian",
-    "arch": "amd64",
-    "variant": "minbase",
-    "extra_packages": ["apt", "systemd", "bash"]
-  }
-}
-```
-
-### 2. `org.osbuild.apt.config`
-
-Configures APT package manager settings, including sources and preferences.
-
-**Options:**
-- `sources` (object, optional): Debian package sources configuration
-- `preferences` (object, optional): Package preferences and pinning configuration
-- `apt_proxy` (string, optional): apt-cacher-ng proxy URL
-
-**Example:**
-```json
-{
-  "type": "org.osbuild.apt.config",
-  "options": {
-    "sources": {
-      "debian": "deb http://deb.debian.org/debian trixie main\n"
-    }
-  }
-}
-```
-
-### 3. `org.osbuild.apt`
-
-Installs Debian packages using APT package manager.
-
-**Options:**
-- `packages` (array, required): List of packages to install
-- `recommends` (boolean, optional): Install recommended packages (default: false)
-- `unauthenticated` (boolean, optional): Allow unauthenticated packages (default: false)
-- `update` (boolean, optional): Update package lists before installation (default: true)
-- `apt_proxy` (string, optional): apt-cacher-ng proxy URL
-
-**Example:**
-```json
-{
-  "type": "org.osbuild.apt",
-  "options": {
-    "packages": [
-      "linux-image-amd64",
-      "systemd",
-      "openssh-server",
-      "curl",
-      "vim"
-    ],
-    "recommends": false,
-    "update": true
-  }
-}
-```
-
-### 4. `org.osbuild.debian.source`
-
-Downloads and manages Debian source packages.
-
-**Options:**
-- `source_package` (string, required): Source package to download
-- `suite` (string, optional): Debian suite to download from (default: "bookworm")
-- `mirror` (string, optional): Debian mirror URL
-- `apt_proxy` (string, optional): apt-cacher-ng proxy URL
-
-**Example:**
-```json
-{
-  "type": "org.osbuild.debian.source",
-  "options": {
-    "source_package": "linux",
-    "suite": "trixie",
-    "mirror": "http://deb.debian.org/debian"
-  }
-}
-```
-
-## Complete Example
-
-Here's a complete example manifest that creates a minimal Debian Trixie image:
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64",
-            "variant": "minbase",
-            "extra_packages": ["apt", "systemd", "bash"]
-          }
-        },
-        {
-          "type": "org.osbuild.apt.config",
-          "options": {
-            "sources": {
-              "debian": "deb http://deb.debian.org/debian trixie main\n"
-            }
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": [
-              "linux-image-amd64",
-              "systemd",
-              "openssh-server",
-              "curl",
-              "vim"
-            ],
-            "recommends": false,
-            "update": true
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Features
-
-### Repository Management
-- Support for multiple APT repositories
-- Custom `sources.list` configuration
-- GPG key handling for repository authentication
-- Proxy support for apt-cacher-ng
-
-### Package Management
-- Full APT package installation
-- Dependency resolution using APT's solver
-- Package recommendations control
-- Unauthenticated package support
-
-### Cross-Architecture Support
-- Support for amd64, arm64, and other architectures
-- Architecture-specific package installation
-- Multi-arch repository support
-
-### Performance Features
-- APT caching and optimization
-- Non-interactive operation (DEBIAN_FRONTEND=noninteractive)
-- Package cache cleanup
-- Proxy support for faster downloads
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Package not found**: Ensure the package name is correct and available in the specified suite
-2. **Repository errors**: Check the mirror URL and suite name
-3. **Architecture issues**: Verify the target architecture is supported
-4. **Network issues**: Use apt-cacher-ng proxy for faster downloads
-
-### Debug Mode
-
-Use the `--break` option to debug stage execution:
-
-```bash
-python3 -m osbuild manifest.json --break org.osbuild.apt
-```
-
-### Logs
-
-Check the build logs for detailed error information:
-
-```bash
-python3 -m osbuild manifest.json --json | jq '.log'
-```
-
-## See Also
-
-- [Debian Forge Documentation](../README.md)
-- [Example Manifests](../test/data/manifests/debian/)
-- [OSBuild Documentation](https://osbuild.org/)

docs/deb-mock-integration-status.md

@@ -1,191 +0,0 @@
-# Mock Integration Status for debian-forge
-
-## 🎯 **Overview**
-
-The integration between `debian-forge` and `mock` (formerly `deb-mock`) has been successfully implemented and tested. While the `mock` packages have a dependency issue in the current repository, our integration code is **production-ready** and will work seamlessly once the packaging issue is resolved.
-
-## 📊 **Current Status**
-
-### **✅ COMPLETED - Integration Implementation**
-- **Mock Stage Implementation** - Complete `org.osbuild.mock` stage
-- **APT Mock Integration** - `org.osbuild.apt.mock` stage for APT operations within mock
-- **Environment Management** - Mock environment lifecycle management
-- **Testing Framework** - Comprehensive test suite with 100% pass rate
-- **Documentation** - Complete integration guides and API documentation
-
-### **⚠️ PENDING - Package Availability**
-- **deb-mock Installation** - Blocked by `shadow-utils` dependency issue
-- **Full Integration Testing** - Requires working `deb-mock` installation
-- **Production Deployment** - Waiting for package dependency resolution
-
-## 🧪 **Test Results**
-
-### **Mock Integration Test Suite**
-```
-==========================================
-Mock Integration Test Summary
-==========================================
-Total tests: 4
-Passed: 4
-Failed: 0
-Success rate: 100%
-==========================================
-```
-
-#### **✅ Tests Passing**
-1. **Mock Stage Syntax** - Python code compiles correctly
-2. **Mock Stage Schema** - JSON schemas are valid
-3. **Mock Build Manifest** - Manifest validation works
-4. **Mock APT Integration Manifest** - APT integration manifests are valid
-
-#### **⚠️ Tests Skipped (Expected)**
-- Mock stage execution tests (requires `deb-mock` installation)
-- Mock environment tests (requires `deb-mock` installation)
-- Mock file operation tests (requires `deb-mock` installation)
-- Mock command execution tests (requires `deb-mock` installation)
-
-## 🔧 **Implementation Details**
-
-### **1. Mock Stage (`org.osbuild.deb-mock`)**
-```python
-def main(tree, options):
-    """Main function for deb-mock stage."""
-    # Mock environment provisioning
-    # Configuration mapping
-    # Environment lifecycle management
-    # Integration with debian-forge stages
-```
-
-**Features:**
-- Mock environment creation and management
-- Configuration mapping between debian-forge and deb-mock
-- Environment lifecycle management (create, use, cleanup)
-- Integration with existing debian-forge stages
-
-### **2. APT Mock Integration (`org.osbuild.apt.mock`)**
-```python
-def main(tree, options):
-    """Main function for APT operations within mock environments."""
-    # Mock client initialization
-    # APT command execution through mock
-    # Environment variable management
-    # Mount point handling
-```
-
-**Features:**
-- APT operations within mock chroots
-- Command execution through mock's chroot system
-- Environment variable and mount point management
-- Integration with deb-mock's Python API
-
-### **3. Test Suite**
-- **Syntax Validation** - Python code compilation
-- **Schema Validation** - JSON schema compliance
-- **Manifest Validation** - Build manifest structure
-- **Integration Testing** - Mock environment operations
-
-## 📦 **Package Status**
-
-### **Available Packages**
-```
-mock - Debian package build environment manager
-mock-cache - Advanced caching and optimization for deb-mock
-mock-configs - Pre-built configurations for different distributions
-mock-dev - Development tools and headers for deb-mock
-mock-filesystem - Filesystem layout and chroot structure for deb-mock
-mock-plugins - Extended functionality through plugins for deb-mock
-```
-
-### **Dependency Issue**
-```
-Unsatisfied dependencies:
- mock-filesystem : Depends: shadow-utils but it is not installable
-```
-
-**Root Cause:** The `shadow-utils` package is not available in the current repository, but `passwd` (which provides shadow utilities) is installed.
-
-**Resolution:** The `deb-mock` package needs to be updated to depend on `passwd` instead of `shadow-utils`, or the repository needs to include `shadow-utils`.
-
-## 🚀 **Integration Capabilities**
-
-### **When deb-mock is Available**
-
-#### **1. Mock Environment Management**
-- Create isolated chroot environments
-- Configure distribution-specific settings
-- Manage environment lifecycle
-- Clean up after builds
-
-#### **2. APT Operations in Mock**
-- Install packages within mock chroots
-- Configure APT repositories
-- Manage package dependencies
-- Execute APT commands safely
-
-#### **3. Build Process Integration**
-- Integrate with debian-forge build pipeline
-- Provide isolated build environments
-- Support reproducible builds
-- Enable parallel build execution
-
-### **Current Workarounds**
-
-#### **1. Code Validation**
-- All integration code is syntactically correct
-- Schemas are valid and well-formed
-- Manifests follow proper structure
-- Error handling is comprehensive
-
-#### **2. Documentation**
-- Complete integration guides available
-- API documentation provided
-- Usage examples included
-- Troubleshooting guides ready
-
-#### **3. Testing Framework**
-- Comprehensive test suite implemented
-- Automated validation available
-- Error detection and reporting
-- Performance monitoring ready
-
-## 📋 **Next Steps**
-
-### **Immediate Actions**
-1. **Package Issue Resolution** - Work with deb-mock team to fix dependency
-2. **Alternative Installation** - Explore manual installation options
-3. **Dependency Mapping** - Verify actual requirements vs. declared dependencies
-
-### **When Packages are Available**
-1. **Full Integration Testing** - Run complete test suite with real deb-mock
-2. **Performance Validation** - Test mock operations under load
-3. **Production Deployment** - Deploy to CI/CD pipeline
-4. **User Documentation** - Create end-user guides
-
-### **Long-term Enhancements**
-1. **Advanced Mock Features** - Leverage mock-cache and mock-plugins
-2. **Performance Optimization** - Implement caching strategies
-3. **Multi-Architecture Support** - Cross-compilation capabilities
-4. **Cloud Integration** - Container and cloud image building
-
-## 🎉 **Achievement Summary**
-
-### **✅ What We've Accomplished**
-- **Complete Integration Code** - All mock integration stages implemented
-- **Comprehensive Testing** - 100% test pass rate for available tests
-- **Production-Ready Code** - Error handling, validation, documentation
-- **Future-Proof Design** - Ready for immediate deployment when packages are available
-
-### **🚀 Ready for Production**
-The debian-forge mock integration is **production-ready** and will work immediately once the `deb-mock` package dependency issue is resolved. The integration provides:
-
-- **Native Debian Support** - Full APT integration within mock environments
-- **Isolated Build Environments** - Clean, reproducible builds
-- **Advanced Package Management** - Beyond what upstream osbuild provides
-- **Comprehensive Testing** - Thorough validation and error handling
-
-### **📊 Impact**
-This integration makes `debian-forge` the **first osbuild-based system** to provide native mock integration for Debian/Ubuntu systems, providing capabilities that are not available in the upstream project.
-
-**Status: PRODUCTION READY** 🚀
-**Blocking Issue: Package dependency resolution** ⚠️
-**Resolution: Contact deb-mock team for dependency fix** 📞

docs/debian-image-building-tutorial.md

@@ -1,299 +0,0 @@
-# Debian Image Building Tutorial
-
-This tutorial will guide you through building Debian images using `debian-forge`, a Debian-specific fork of OSBuild with full APT support.
-
-## Prerequisites
-
-- `debian-forge` installed (see [Installation Guide](installation.md))
-- Basic understanding of Debian package management
-- Familiarity with JSON manifest format
-
-## Quick Start
-
-### 1. Basic Debian Image
-
-Let's start with a simple Debian Trixie minimal image:
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64",
-            "variant": "minbase"
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": ["linux-image-amd64", "systemd", "openssh-server"]
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-Save this as `debian-minimal.json` and build it:
-
-```bash
-python3 -m osbuild debian-minimal.json --output-dir ./output --libdir .
-```
-
-### 2. Server Image with Custom Packages
-
-For a server image, we'll add more packages and configuration:
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64",
-            "variant": "minbase",
-            "extra_packages": ["apt", "systemd", "bash"]
-          }
-        },
-        {
-          "type": "org.osbuild.apt.config",
-          "options": {
-            "sources": {
-              "debian": "deb http://deb.debian.org/debian trixie main\n"
-            }
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": [
-              "linux-image-amd64",
-              "systemd",
-              "openssh-server",
-              "nginx",
-              "mysql-server",
-              "python3",
-              "curl",
-              "vim",
-              "htop"
-            ],
-            "recommends": false,
-            "update": true
-          }
-        },
-        {
-          "type": "org.osbuild.hostname",
-          "options": {
-            "hostname": "debian-server"
-          }
-        },
-        {
-          "type": "org.osbuild.systemd",
-          "options": {
-            "enabled_services": [
-              "sshd",
-              "systemd-networkd",
-              "systemd-resolved",
-              "nginx",
-              "mysql"
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 3. Ubuntu Image
-
-Building Ubuntu images is similar, just change the suite and mirror:
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "jammy",
-            "mirror": "http://archive.ubuntu.com/ubuntu",
-            "arch": "amd64",
-            "variant": "minbase"
-          }
-        },
-        {
-          "type": "org.osbuild.apt.config",
-          "options": {
-            "sources": {
-              "ubuntu": "deb http://archive.ubuntu.com/ubuntu jammy main restricted universe multiverse\n"
-            }
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": [
-              "linux-image-generic",
-              "systemd",
-              "openssh-server",
-              "curl",
-              "vim"
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Advanced Features
-
-### Custom Repositories
-
-Add custom repositories for additional packages:
-
-```json
-{
-  "type": "org.osbuild.apt.config",
-  "options": {
-    "sources": {
-      "debian": "deb http://deb.debian.org/debian trixie main\n",
-      "debian-forge": "deb https://git.raines.xyz/api/packages/particle-os/debian trixie main\n"
-    }
-  }
-}
-```
-
-### Package Preferences
-
-Configure package pinning and preferences:
-
-```json
-{
-  "type": "org.osbuild.apt.config",
-  "options": {
-    "preferences": {
-      "debian-forge": "Package: *\nPin: origin git.raines.xyz\nPin-Priority: 1000\n"
-    }
-  }
-}
-```
-
-### Cross-Architecture Builds
-
-Build for different architectures:
-
-```json
-{
-  "type": "org.osbuild.debootstrap",
-  "options": {
-    "suite": "trixie",
-    "mirror": "http://deb.debian.org/debian",
-    "arch": "arm64",
-    "variant": "minbase"
-  }
-}
-```
-
-### APT Proxy
-
-Use apt-cacher-ng for faster builds:
-
-```json
-{
-  "type": "org.osbuild.apt",
-  "options": {
-    "packages": ["linux-image-amd64"],
-    "apt_proxy": "http://localhost:3142"
-  }
-}
-```
-
-## Best Practices
-
-### 1. Package Selection
-
-- Use `recommends: false` to avoid installing unnecessary packages
-- Include only essential packages in the base image
-- Use `extra_packages` in debootstrap for core system packages
-
-### 2. Repository Configuration
-
-- Always configure APT sources explicitly
-- Use HTTPS mirrors when available
-- Consider using apt-cacher-ng for faster builds
-
-### 3. Service Configuration
-
-- Enable only necessary services
-- Use systemd for service management
-- Configure hostname and network settings
-
-### 4. Security
-
-- Keep packages updated
-- Use minimal base images
-- Configure firewall rules appropriately
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Package not found**: Check package name and availability
-2. **Repository errors**: Verify mirror URL and suite name
-3. **Architecture issues**: Ensure target architecture is supported
-4. **Network issues**: Use apt-cacher-ng proxy
-
-### Debug Mode
-
-Use the `--break` option to debug specific stages:
-
-```bash
-python3 -m osbuild manifest.json --break org.osbuild.apt
-```
-
-### Logs
-
-Check build logs for detailed information:
-
-```bash
-python3 -m osbuild manifest.json --json | jq '.log'
-```
-
-## Examples
-
-See the [example manifests](../test/data/manifests/debian/) for more complete examples:
-
-- `debian-trixie-minimal.json` - Minimal Debian Trixie image
-- `ubuntu-jammy-server.json` - Ubuntu Jammy server image
-- `debian-atomic-container.json` - Debian Atomic container image
-- `debian-trixie-arm64.json` - ARM64 cross-architecture build
-
-## Next Steps
-
-- [APT Stages Reference](apt-stages.md)
-- [Container Image Building](container-image-building.md)
-- [Cloud Image Generation](cloud-image-generation.md)
-- [Performance Optimization](performance-optimization.md)

docs/debian-runners.md

@@ -1,328 +0,0 @@
-# Debian Runner System
-
-This document explains how Debian Forge implements a dynamic runner system similar to Fedora OSBuild, automatically detecting and using the appropriate runner for different Debian-based distributions.
-
-## Overview
-
-Just like Fedora OSBuild automatically detects and uses the right runner for different Fedora versions, Debian Forge now provides the same functionality for Debian-based distributions.
-
-## How It Works
-
-### 1. Automatic Detection
-The system automatically detects your distribution and creates a symbolic link to the appropriate runner:
-
-```bash
-# Fedora-style automatic detection
-$ ls -la runners/
-org.osbuild.fedora38*    # Fedora 38 runner
-org.osbuild.fedora39*    # Fedora 39 runner  
-org.osbuild.fedora40*    # Fedora 40 runner
-org.osbuild.fedora41*    # Fedora 41 runner
-org.osbuild.linux*       # Generic Linux runner
-
-# Debian Forge equivalent
-$ ls -la runners/
-org.osbuild.debian13*    # Debian 13 (Trixie) runner
-org.osbuild.debian14*    # Debian 14 (Forky) runner
-org.osbuild.ubuntu2504*  # Ubuntu 25.04 (Plucky Puffin) runner
-org.osbuild.ubuntu2404*  # Ubuntu 24.04 (Noble Numbat) runner
-org.osbuild.debian-based* # Generic Debian-based runner
-org.osbuild.linux*       # Generic Linux runner
-```
-
-### 2. Dynamic Runner Mapping
-When you run OSBuild, it automatically uses the runner that matches your system:
-
-```bash
-# On Debian Trixie (13)
-$ python3 -m osbuild --libdir . manifest.json
-# Automatically uses org.osbuild.debian13
-
-# On Ubuntu 25.04
-$ python3 -m osbuild --libdir . manifest.json  
-# Automatically uses org.osbuild.ubuntu2504
-
-# On your current system (bazzite)
-$ python3 -m osbuild --libdir . manifest.json
-# Automatically uses org.osbuild.bazzite -> org.osbuild.linux
-```
-
-## Available Runners
-
-### 🐧 Debian Runners
-
-| Runner | Distribution | Version | Status | Description |
-|--------|--------------|---------|---------|-------------|
-| `org.osbuild.debian13` | Debian | 13 (Trixie) | **STABLE** | Production-ready Debian 13 |
-| `org.osbuild.debian14` | Debian | 14 (Forky) | **TESTING** | Development/testing Debian 14 |
-| `org.osbuild.debian-sid` | Debian | Sid | **UNSTABLE** | Unstable development (use with caution) |
-| `org.osbuild.debian` | Debian | Generic | **LEGACY** | Generic Debian runner |
-| `org.osbuild.debian-based` | Debian-based | Generic | **GENERIC** | Other Debian derivatives |
-
-### 🦊 Ubuntu Runners
-
-| Runner | Distribution | Version | Codename | Status |
-|--------|--------------|---------|----------|---------|
-| `org.osbuild.ubuntu2504` | Ubuntu | 25.04 | Plucky Puffin | **LTS** |
-| `org.osbuild.ubuntu2404` | Ubuntu | 24.04 | Noble Numbat | **LTS** |
-| `org.osbuild.ubuntu1804` | Ubuntu | 18.04 | Bionic Beaver | **LTS** |
-
-### 🔧 Other Runners
-
-| Runner | Distribution | Type |
-|--------|--------------|------|
-| `org.osbuild.linux` | Generic Linux | **FALLBACK** |
-| `org.osbuild.fedora*` | Fedora variants | **EXISTING** |
-| `org.osbuild.rhel*` | RHEL variants | **EXISTING** |
-
-## Runner Features
-
-### Debian-Specific Optimizations
-
-Each Debian runner includes:
-
-- **Environment Variables**: `DEBIAN_FRONTEND=noninteractive`
-- **Package Management**: Automatic `apt-get update`
-- **Sources Backup**: Automatic backup of `/etc/apt/sources.list`
-- **Distribution Detection**: Automatic codename/version detection
-
-### Ubuntu-Specific Optimizations
-
-Each Ubuntu runner includes:
-
-- **Environment Variables**: Ubuntu-specific settings
-- **LTS Detection**: Automatic LTS release detection
-- **Package Management**: Ubuntu-optimized apt configuration
-- **Version Mapping**: Automatic version-to-codename mapping
-
-### Generic Debian-Based Runner
-
-The `org.osbuild.debian-based` runner automatically detects:
-
-- **Linux Mint**
-- **Pop!_OS**
-- **Elementary OS**
-- **Zorin OS**
-- **Kali Linux**
-- **Parrot OS**
-- **Other Debian derivatives**
-
-## Setup and Usage
-
-### 1. Automatic Setup
-
-The system automatically sets up the right runner for your system:
-
-```bash
-# Automatic detection and setup
-$ ./tools/debian-runner-setup
-
-🔍 Debian Runner Setup Tool
-========================================
-Distribution: unknown
-Version: unknown
-Codename: unknown
-Recommended runner: org.osbuild.linux
-
-✅ Created runner: org.osbuild.bazzite -> org.osbuild.linux
-
-🎯 Runner setup complete!
-   Your system 'bazzite' now uses org.osbuild.linux
-   OSBuild will automatically use the appropriate runner for your system
-```
-
-### 2. Manual Runner Selection
-
-You can manually select a specific runner:
-
-```bash
-# List available runners
-$ ./tools/debian-runner-setup list
-
-# Create a specific runner
-$ ln -sf org.osbuild.debian13 runners/org.osbuild.mysystem
-```
-
-### 3. Runner Verification
-
-Check which runner your system is using:
-
-```bash
-$ ls -la runners/org.osbuild.$(hostname)
-lrwxrwxrwx. 1 user user 17 Aug 26 16:11 org.osbuild.bazzite -> org.osbuild.linux
-```
-
-## Configuration
-
-### Environment Variables
-
-Each runner sets appropriate environment variables:
-
-```bash
-# Debian runners
-DEBIAN_FRONTEND=noninteractive
-DEBCONF_NONINTERACTIVE_SEEN=true
-DEBIAN_TESTING=1          # For testing releases
-DEBIAN_UNSTABLE=1         # For unstable releases
-
-# Ubuntu runners  
-DEBIAN_FRONTEND=noninteractive
-DEBCONF_NONINTERACTIVE_SEEN=true
-UBUNTU_CODENAME=plucky
-UBUNTU_VERSION=25.04
-UBUNTU_LTS=1
-```
-
-### Package Sources
-
-Runners automatically configure appropriate package sources:
-
-```bash
-# Debian 13 (Trixie)
-deb http://deb.debian.org/debian trixie main
-deb http://deb.debian.org/debian trixie-updates main
-deb http://deb.debian.org/debian trixie-security main
-deb http://deb.debian.org/debian trixie-backports main
-
-# Ubuntu 25.04 (Plucky Puffin)
-deb http://archive.ubuntu.com/ubuntu plucky main
-deb http://archive.ubuntu.com/ubuntu plucky-updates main
-deb http://security.ubuntu.com/ubuntu plucky-security main
-```
-
-## Benefits
-
-### ✅ **No Hardcoded Versions**
-- **Before**: Hardcoded `bookworm` everywhere
-- **After**: Automatically detects and uses appropriate version
-
-### ✅ **Cross-Distribution Support**
-- **Debian**: Trixie, Forky, Sid, and future releases
-- **Ubuntu**: 24.04, 25.04, and future LTS releases
-- **Other**: Linux Mint, Pop!_OS, Elementary OS, etc.
-
-### ✅ **Future-Proof**
-- **New releases**: Automatically supported
-- **Version upgrades**: No code changes needed
-- **Distribution changes**: Automatic detection
-
-### ✅ **Fedora-Style Workflow**
-- **Automatic detection**: Like `dnf` detecting Fedora version
-- **Smart defaults**: Like OSBuild choosing the right runner
-- **Graceful fallbacks**: Like falling back to generic Linux runner
-
-## Examples
-
-### On Debian Trixie (13)
-```bash
-$ ./tools/debian-runner-setup
-Distribution: debian
-Codename: trixie
-Recommended runner: org.osbuild.debian13
-
-✅ Created runner: org.osbuild.trixie -> org.osbuild.debian13
-```
-
-### On Ubuntu 25.04
-```bash
-$ ./tools/debian-runner-setup
-Distribution: ubuntu
-Version: 25.04
-Recommended runner: org.osbuild.ubuntu2504
-
-✅ Created runner: org.osbuild.plucky -> org.osbuild.ubuntu2504
-```
-
-### On Linux Mint
-```bash
-$ ./tools/debian-runner-setup
-Distribution: debian-based
-Recommended runner: org.osbuild.debian-based
-
-✅ Created runner: org.osbuild.mint -> org.osbuild.debian-based
-```
-
-## Troubleshooting
-
-### Runner Not Found
-```bash
-$ ./tools/debian-runner-setup
-❌ Recommended runner org.osbuild.debian13 not found!
-   Available runners:
-   - org.osbuild.debian
-   - org.osbuild.linux
-   - org.osbuild.ubuntu1804
-```
-
-**Solution**: Use `./tools/debian-runner-setup list` to see available runners and manually create the link.
-
-### Permission Denied
-```bash
-❌ Failed to create runner: [Errno 13] Permission denied
-```
-
-**Solution**: Ensure you have write permissions to the `runners/` directory.
-
-### Distribution Not Detected
-```bash
-Distribution: unknown
-Recommended runner: org.osbuild.linux
-```
-
-**Solution**: The system falls back to the generic Linux runner, which should work for most cases.
-
-## Integration with OSBuild
-
-### Automatic Runner Selection
-
-OSBuild automatically selects the appropriate runner based on your system:
-
-```python
-# OSBuild automatically finds the right runner
-runner = osbuild.find_runner()  # Returns org.osbuild.debian13 on Debian Trixie
-```
-
-### Runner Priority
-
-OSBuild uses this priority order for runner selection:
-
-1. **System-specific runner** (e.g., `org.osbuild.bazzite`)
-2. **Distribution-specific runner** (e.g., `org.osbuild.debian13`)
-3. **Generic runner** (e.g., `org.osbuild.linux`)
-
-### Fallback Behavior
-
-If no specific runner is found, the system gracefully falls back:
-
-```bash
-# No specific runner found
-$ python3 -m osbuild --libdir . manifest.json
-# Automatically uses org.osbuild.linux
-# No errors, just generic Linux behavior
-```
-
-## Future Enhancements
-
-### Planned Features
-
-- **Automatic runner updates**: Update runners when new distributions are detected
-- **Custom runner creation**: Allow users to create custom runners
-- **Runner validation**: Validate runner compatibility with current system
-- **Performance optimization**: Optimize runners for specific distributions
-
-### Distribution Support
-
-- **Debian**: All future releases (15, 16, etc.)
-- **Ubuntu**: All future LTS releases (26.04, 28.04, etc.)
-- **Other**: More Debian derivatives (MX Linux, SparkyLinux, etc.)
-
-## Conclusion
-
-The Debian runner system provides the same level of automation and intelligence as Fedora OSBuild, automatically detecting your distribution and using the appropriate runner. This eliminates the need for hardcoded versions and provides a seamless, future-proof experience across all Debian-based distributions.
-
-**Key Benefits:**
-- 🚀 **Automatic detection** like Fedora
-- 🔄 **Future-proof** for new releases  
-- 🎯 **Distribution-specific** optimizations
-- ⚡ **Zero configuration** required
-- 🛡️ **Graceful fallbacks** for compatibility

docs/mock-integration-current-status.md

@@ -1,145 +0,0 @@
-# Mock Integration - Current Status
-
-## 🎯 **Summary**
-
-The mock integration for `debian-forge` is **technically complete and production-ready**, but is currently **blocked by a package dependency issue** that prevents installation of the `mock` package.
-
-## ✅ **What's Working**
-
-### **1. Complete Implementation**
-- **Mock Stage** (`org.osbuild.mock`) - Fully implemented
-- **APT Mock Integration** (`org.osbuild.apt.mock`) - Fully implemented  
-- **Test Suite** - 100% pass rate for available tests
-- **Documentation** - Comprehensive guides and API documentation
-
-### **2. Code Quality**
-- **Syntax Validation** - All Python code compiles correctly
-- **Schema Validation** - All JSON schemas are valid
-- **Manifest Validation** - All build manifests are properly structured
-- **Error Handling** - Comprehensive error handling and validation
-
-### **3. Integration Ready**
-- **Correct Naming** - Updated from deprecated `deb-mock` to `mock`
-- **Import Statements** - Properly configured for `mock` package
-- **API Integration** - Ready to work with mock's Python API
-- **Environment Management** - Complete lifecycle management
-
-## ⚠️ **Current Blocker**
-
-### **Package Dependency Issue**
-```
-mock → mock-filesystem → shadow-utils (NOT AVAILABLE)
-```
-
-**Problem**: `mock-filesystem` depends on `shadow-utils` which doesn't exist in Debian Trixie
-**Solution**: `shadow-utils` should be replaced with `passwd` (which provides the same functionality)
-
-### **Impact**
-- **Mock Installation**: Cannot install `mock` package
-- **Integration Testing**: Cannot test full mock functionality
-- **Production Deployment**: Mock features unavailable to users
-
-## 🧪 **Test Results**
-
-### **Available Tests (All Passing)**
-```
-==========================================
-Mock Integration Test Summary
-==========================================
-Total tests: 4
-Passed: 4
-Failed: 0
-Success rate: 100%
-==========================================
-```
-
-#### **✅ Tests Passing**
-1. **Mock Stage Syntax** - Python code compiles correctly
-2. **Mock Stage Schema** - JSON schemas are valid
-3. **Mock Build Manifest** - Manifest validation works
-4. **Mock APT Integration Manifest** - APT integration manifests are valid
-
-#### **⚠️ Tests Skipped (Expected)**
-- Mock stage execution tests (requires `mock` package installation)
-- Mock environment tests (requires `mock` package installation)
-- Mock file operation tests (requires `mock` package installation)
-- Mock command execution tests (requires `mock` package installation)
-
-## 🚀 **Next Steps**
-
-### **Immediate (Today)**
-- [x] Document the dependency issue
-- [x] Identify root cause and solution
-- [x] Create comprehensive issue report
-
-### **Short Term (1-2 days)**
-- [ ] Contact deb-mock team about dependency fix
-- [ ] Provide detailed issue report and solution
-- [ ] Wait for package update
-
-### **Medium Term (1 week)**
-- [ ] Test updated mock package
-- [ ] Run complete integration test suite
-- [ ] Deploy to production
-
-## 📊 **Technical Details**
-
-### **Dependency Analysis**
-```bash
-# What's available
-$ apt-cache search shadow | grep -E "(shadow|passwd|useradd|groupadd)"
-passwd - change and administer password and group data
-
-# What's missing
-$ apt-cache search shadow-utils
-libvshadow-utils - Volume Shadow Snapshot format access library -- Utilities
-# (This is NOT the same as shadow-utils)
-```
-
-### **Required Fix**
-```diff
-# In mock-filesystem package
-- Depends: shadow-utils
-+ Depends: passwd
-```
-
-### **Verification**
-```bash
-# Check that passwd provides the required utilities
-$ dpkg -S /usr/sbin/useradd
-passwd: /usr/sbin/useradd
-
-$ dpkg -S /usr/sbin/groupadd  
-passwd: /usr/sbin/groupadd
-```
-
-## 🎉 **Achievement Summary**
-
-### **✅ What We've Accomplished**
-- **Complete Mock Integration** - All stages implemented and tested
-- **Production-Ready Code** - Error handling, validation, documentation
-- **Comprehensive Testing** - 100% pass rate for available tests
-- **Correct Naming** - Updated to use current `mock` package name
-- **Issue Documentation** - Detailed analysis and solution proposal
-
-### **🚀 Ready for Deployment**
-Once the package dependency is fixed:
-1. **Install mock** - `sudo apt install mock` will work
-2. **Run full tests** - Complete integration test suite
-3. **Deploy to production** - Mock features immediately available
-4. **User experience** - Full mock environment capabilities
-
-## 📞 **Contact Information**
-
-- **Issue Report**: `docs/mock-package-dependency-issue.md`
-- **Package Maintainer**: Deb-Mock Team <deb-mock@raines.xyz>
-- **Repository**: https://git.raines.xyz/robojerk/deb-mock
-
-## 🎯 **Conclusion**
-
-The debian-forge mock integration is **technically complete and production-ready**. The only remaining issue is a simple package dependency fix that needs to be addressed by the deb-mock team. Once this is resolved, the integration will work immediately and provide full mock environment capabilities.
-
-**Status**: PRODUCTION READY (blocked by package dependency)
-**Effort Required**: LOW (simple dependency update)
-**Timeline**: 1-2 days (once deb-mock team responds)
-**Impact**: HIGH (enables full mock integration functionality)

docs/mock-integration-guide.md

@@ -1,563 +0,0 @@
-# Mock Integration Guide for debian-forge
-
-This guide provides comprehensive documentation for using the mock integration features in debian-forge, which enable enhanced build isolation and reproducibility through deb-mock chroot environments.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Prerequisites](#prerequisites)
-- [Mock Stage](#mock-stage)
-- [APT Mock Integration](#apt-mock-integration)
-- [Example Manifests](#example-manifests)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
-
-## Overview
-
-The mock integration in debian-forge provides:
-
-- **Enhanced Build Isolation**: Build packages in clean, isolated chroot environments
-- **Reproducible Builds**: Consistent build environments across different systems
-- **Dependency Management**: Advanced APT package management within mock environments
-- **Multi-Architecture Support**: Build for different architectures in isolated environments
-- **Caching**: Efficient caching of build environments and packages
-
-## Prerequisites
-
-### Required Dependencies
-
-1. **deb-mock**: The mock environment manager
-   ```bash
-   # Install deb-mock (when available)
-   pip install deb-mock
-   ```
-
-2. **Python Dependencies**: Already included in debian-forge
-   - `deb-mock` Python API
-   - Standard osbuild dependencies
-
-### System Requirements
-
-- Root privileges (for chroot operations)
-- Sufficient disk space for mock environments
-- Network access for package downloads
-
-## Mock Stage
-
-The `org.osbuild.deb-mock` stage provides core mock environment management.
-
-### Basic Usage
-
-```json
-{
-  "name": "org.osbuild.deb-mock",
-  "options": {
-    "action": "create",
-    "mock_options": {
-      "environment": "my-build-env",
-      "architecture": "amd64",
-      "suite": "trixie"
-    }
-  }
-}
-```
-
-### Available Actions
-
-#### 1. Create Environment
-```json
-{
-  "action": "create",
-  "mock_options": {
-    "environment": "debian-trixie-build",
-    "architecture": "amd64",
-    "suite": "trixie",
-    "packages": ["build-essential", "devscripts"],
-    "cache_enabled": true,
-    "parallel_jobs": 4
-  }
-}
-```
-
-#### 2. Execute Commands
-```json
-{
-  "action": "execute",
-  "mock_options": {
-    "environment": "debian-trixie-build"
-  },
-  "commands": [
-    ["git", "clone", "https://github.com/example/project.git", "/build/project"],
-    ["cd", "/build/project", "&&", "make", "all"]
-  ]
-}
-```
-
-#### 3. Install Packages
-```json
-{
-  "action": "install_packages",
-  "mock_options": {
-    "environment": "debian-trixie-build"
-  },
-  "packages": ["cmake", "ninja-build", "git"]
-}
-```
-
-#### 4. Copy Files
-```json
-{
-  "action": "copy_files",
-  "mock_options": {
-    "environment": "debian-trixie-build"
-  },
-  "copy_operations": [
-    {
-      "type": "in",
-      "source": "/host/source",
-      "destination": "/build/source"
-    },
-    {
-      "type": "out",
-      "source": "/build/artifacts",
-      "destination": "/host/artifacts"
-    }
-  ]
-}
-```
-
-#### 5. Collect Artifacts
-```json
-{
-  "action": "collect_artifacts",
-  "mock_options": {
-    "environment": "debian-trixie-build"
-  },
-  "source_patterns": ["*.deb", "*.changes", "*.buildinfo"],
-  "output_dir": "/tmp/build-artifacts"
-}
-```
-
-#### 6. Destroy Environment
-```json
-{
-  "action": "destroy",
-  "mock_options": {
-    "environment": "debian-trixie-build"
-  }
-}
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `environment` | string | "debian-forge-build" | Name of the mock environment |
-| `architecture` | string | "amd64" | Target architecture |
-| `suite` | string | "trixie" | Debian suite |
-| `mirror` | string | "http://deb.debian.org/debian/" | Package mirror URL |
-| `packages` | array | [] | Initial packages to install |
-| `output_dir` | string | "/tmp/mock-output" | Output directory |
-| `cache_enabled` | boolean | true | Enable caching |
-| `parallel_jobs` | integer | 4 | Number of parallel jobs |
-| `verbose` | boolean | false | Verbose output |
-| `debug` | boolean | false | Debug output |
-
-## APT Mock Integration
-
-The `org.osbuild.apt.mock` stage provides APT package management within mock environments.
-
-### Basic Usage
-
-```json
-{
-  "name": "org.osbuild.apt.mock",
-  "options": {
-    "mock_options": {
-      "environment": "debian-trixie-build"
-    },
-    "packages": ["build-essential", "cmake", "git"]
-  }
-}
-```
-
-### Advanced Features
-
-#### Repository Configuration
-```json
-{
-  "repositories": [
-    {
-      "name": "debian-main",
-      "url": "http://deb.debian.org/debian/",
-      "suite": "trixie",
-      "components": ["main", "contrib", "non-free"]
-    },
-    {
-      "name": "debian-security",
-      "url": "http://security.debian.org/debian-security/",
-      "suite": "trixie-security",
-      "components": ["main", "contrib", "non-free"]
-    }
-  ]
-}
-```
-
-#### Package Pinning
-```json
-{
-  "pinning": {
-    "cmake": "3.27.*",
-    "ninja-build": "1.11.*"
-  }
-}
-```
-
-#### Package Holds
-```json
-{
-  "holds": ["cmake", "ninja-build"]
-}
-```
-
-#### Repository Priorities
-```json
-{
-  "priorities": {
-    "debian-main": 500,
-    "debian-security": 600
-  }
-}
-```
-
-#### Specific Versions
-```json
-{
-  "specific_versions": {
-    "cmake": "3.27.7-1",
-    "ninja-build": "1.11.1-1"
-  }
-}
-```
-
-## Example Manifests
-
-### Complete Build Workflow
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "name": "build",
-      "runner": "org.osbuild.linux",
-      "stages": [
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "create",
-            "mock_options": {
-              "environment": "debian-trixie-build",
-              "architecture": "amd64",
-              "suite": "trixie",
-              "packages": ["build-essential", "devscripts", "cmake"]
-            }
-          }
-        },
-        {
-          "name": "org.osbuild.apt.mock",
-          "options": {
-            "mock_options": {
-              "environment": "debian-trixie-build"
-            },
-            "packages": ["ninja-build", "git", "python3-dev"]
-          }
-        },
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "copy_files",
-            "mock_options": {
-              "environment": "debian-trixie-build"
-            },
-            "copy_operations": [
-              {
-                "type": "in",
-                "source": "/host/source",
-                "destination": "/build/source"
-              }
-            ]
-          }
-        },
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "execute",
-            "mock_options": {
-              "environment": "debian-trixie-build"
-            },
-            "commands": [
-              ["cd", "/build/source"],
-              ["dpkg-buildpackage", "-b", "-us", "-uc"]
-            ]
-          }
-        },
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "collect_artifacts",
-            "mock_options": {
-              "environment": "debian-trixie-build"
-            },
-            "source_patterns": ["*.deb", "*.changes", "*.buildinfo"],
-            "output_dir": "/tmp/build-artifacts"
-          }
-        },
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "destroy",
-            "mock_options": {
-              "environment": "debian-trixie-build"
-            }
-          }
-        }
-      ]
-    }
-  ],
-  "sources": {}
-}
-```
-
-### Multi-Architecture Build
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "name": "build-amd64",
-      "runner": "org.osbuild.linux",
-      "stages": [
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "create",
-            "mock_options": {
-              "environment": "debian-trixie-amd64",
-              "architecture": "amd64",
-              "suite": "trixie"
-            }
-          }
-        },
-        {
-          "name": "org.osbuild.apt.mock",
-          "options": {
-            "mock_options": {
-              "environment": "debian-trixie-amd64"
-            },
-            "packages": ["build-essential", "cmake"]
-          }
-        }
-      ]
-    },
-    {
-      "name": "build-arm64",
-      "runner": "org.osbuild.linux",
-      "stages": [
-        {
-          "name": "org.osbuild.deb-mock",
-          "options": {
-            "action": "create",
-            "mock_options": {
-              "environment": "debian-trixie-arm64",
-              "architecture": "arm64",
-              "suite": "trixie"
-            }
-          }
-        },
-        {
-          "name": "org.osbuild.apt.mock",
-          "options": {
-            "mock_options": {
-              "environment": "debian-trixie-arm64"
-            },
-            "packages": ["build-essential", "cmake"]
-          }
-        }
-      ]
-    }
-  ],
-  "sources": {}
-}
-```
-
-## Best Practices
-
-### 1. Environment Naming
-- Use descriptive names: `debian-trixie-amd64-build`
-- Include architecture and suite in the name
-- Use consistent naming across your project
-
-### 2. Resource Management
-- Always destroy environments when done
-- Use caching for frequently used environments
-- Monitor disk usage for mock environments
-
-### 3. Error Handling
-- Check if environments exist before using them
-- Handle command failures gracefully
-- Clean up on errors
-
-### 4. Security
-- Use minimal package sets
-- Keep environments isolated
-- Regularly update base images
-
-### 5. Performance
-- Enable caching for repeated builds
-- Use parallel jobs appropriately
-- Clean up unused environments
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. Environment Creation Fails
-```
-Error: deb-mock package not available
-```
-**Solution**: Install deb-mock package
-```bash
-pip install deb-mock
-```
-
-#### 2. Permission Denied
-```
-Error: Permission denied for chroot operations
-```
-**Solution**: Run with root privileges
-```bash
-sudo osbuild --output-dir /tmp/output manifest.json
-```
-
-#### 3. Package Installation Fails
-```
-Error: Package installation failed
-```
-**Solution**: Check package names and repository configuration
-- Verify package names are correct
-- Ensure repositories are properly configured
-- Check network connectivity
-
-#### 4. Environment Not Found
-```
-Error: Environment does not exist
-```
-**Solution**: Create the environment first
-```json
-{
-  "action": "create",
-  "mock_options": {
-    "environment": "my-env"
-  }
-}
-```
-
-### Debug Mode
-
-Enable debug mode for detailed logging:
-
-```json
-{
-  "mock_options": {
-    "debug": true,
-    "verbose": true
-  }
-}
-```
-
-### Logging
-
-Check the build logs for detailed error information:
-
-```bash
-# Check osbuild logs
-journalctl -u osbuild
-
-# Check mock environment logs
-ls /var/log/mock/
-```
-
-### Performance Issues
-
-If builds are slow:
-
-1. Enable caching:
-   ```json
-   {
-     "mock_options": {
-       "cache_enabled": true
-     }
-   }
-   ```
-
-2. Increase parallel jobs:
-   ```json
-   {
-     "mock_options": {
-       "parallel_jobs": 8
-     }
-   }
-   ```
-
-3. Use faster mirrors:
-   ```json
-   {
-     "mock_options": {
-       "mirror": "http://fast-mirror.debian.org/debian/"
-     }
-   }
-   ```
-
-## Integration with CI/CD
-
-### GitHub Actions Example
-
-```yaml
-name: Build with Mock
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Install deb-mock
-        run: pip install deb-mock
-      - name: Build with mock
-        run: |
-          sudo osbuild --output-dir artifacts \
-            --libdir . \
-            --json test/data/manifests/debian/debian-mock-build.json
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v3
-        with:
-          name: build-artifacts
-          path: artifacts/
-```
-
-### GitLab CI Example
-
-```yaml
-build:
-  stage: build
-  script:
-    - pip install deb-mock
-    - sudo osbuild --output-dir artifacts --libdir . --json manifest.json
-  artifacts:
-    paths:
-      - artifacts/
-```
-
-This guide provides comprehensive coverage of the mock integration features in debian-forge. For more examples and advanced usage, see the example manifests in `test/data/manifests/debian/`.

docs/mock-integration.md

@@ -1,398 +0,0 @@
-# Debian Forge Mock Integration Plan
-
-## Overview
-
-This document outlines the integration plan for [deb-mock](https://git.raines.xyz/particle-os/deb-mock) with debian-forge to create a comprehensive Debian image building ecosystem. The integration will provide isolated, reproducible build environments for Debian package and image creation.
-
-## Current State Analysis
-
-### **debian-forge** - The Image Building Engine ( fork of Fedora's osbuild)
-- **Status**: Production-ready with comprehensive APT support
-- **Capabilities**: Complete Debian/Ubuntu image building with APT stages
-- **Architecture**: OSBuild-based pipeline system with modular stages
-- **Strengths**: Full APT integration, cross-architecture support, comprehensive testing
-
-### **deb-mock** - The Build Environment Manager
-- **Status**: Foundation development phase (Phase 1)
-- **Capabilities**: Chroot environment management, package installation, isolation
-- **Architecture**: Single-process, multi-stage with plugin system
-- **Strengths**: Clean build environments, dependency management, security isolation
-
-## Integration Architecture
-
-### **The Complete Debian Image Building Ecosystem**
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                    Debian Image Building Stack                 │
-├─────────────────────────────────────────────────────────────────┤
-│  debian-forge (OSBuild)  │  deb-mock (Environment)  │  Output  │
-│  ┌─────────────────────┐  │  ┌─────────────────────┐  │  ┌─────┐ │
-│  │  Pipeline Engine    │  │  │  Chroot Manager     │  │  │ .deb│ │
-│  │  - APT Stages       │  │  │  - Environment      │  │  │ .iso│ │
-│  │  - Debian Support   │  │  │  - Isolation        │  │  │ .img│ │
-│  │  - Cross-arch       │  │  │  - Dependencies     │  │  │ etc │ │
-│  └─────────────────────┘  │  └─────────────────────┘  │  └─────┘ │
-│           │                │           │                │         │
-│           └────────────────┼───────────┘                │         │
-│                            │                            │         │
-│  ┌─────────────────────────▼─────────────────────────┐  │         │
-│  │              Integration Layer                    │  │         │
-│  │  - Mock Environment Provisioning                  │  │         │
-│  │  - Build Command Execution                        │  │         │
-│  │  - Artifact Collection                            │  │         │
-│  └───────────────────────────────────────────────────┘  │         │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Integration Phases
-
-### **Phase 1: Basic Integration (Weeks 1-4)**
-
-#### **1.1 Mock Environment Provisioning**
-- **Goal**: Integrate deb-mock as the build environment provider for debian-forge
-- **Implementation**:
-  - Create `org.osbuild.deb-mock` stage for environment provisioning
-  - Implement mock environment lifecycle management
-  - Add configuration mapping between debian-forge and deb-mock
-
-#### **1.2 Build Command Execution**
-- **Goal**: Execute debian-forge stages within mock environments
-- **Implementation**:
-  - Modify existing APT stages to work within mock chroots
-  - Implement command execution through mock's chroot system
-  - Add environment variable and mount point management
-
-#### **1.3 Basic Testing**
-- **Goal**: Ensure basic integration works end-to-end
-- **Implementation**:
-  - Create integration test manifests
-  - Test simple Debian image builds
-  - Validate artifact collection and output
-
-### **Phase 2: Advanced Integration (Weeks 5-8)**
-
-#### **2.1 Plugin System Integration**
-- **Goal**: Leverage deb-mock's plugin system for enhanced functionality
-- **Implementation**:
-  - Integrate with deb-mock's plugin architecture
-  - Create debian-forge specific plugins
-  - Implement caching and optimization plugins
-
-#### **2.2 Multi-Environment Support**
-- **Goal**: Support multiple Debian distributions and architectures
-- **Implementation**:
-  - Extend mock configuration for different Debian suites
-  - Add cross-architecture build support
-  - Implement environment-specific optimizations
-
-#### **2.3 Performance Optimization**
-- **Goal**: Optimize build performance through mock integration
-- **Implementation**:
-  - Implement build environment caching
-  - Add parallel build support
-  - Optimize package installation and dependency resolution
-
-### **Phase 3: Production Integration (Weeks 9-12)**
-
-#### **3.1 CI/CD Integration**
-- **Goal**: Integrate with Forgejo CI/CD for automated builds
-- **Implementation**:
-  - Update CI workflows to use mock environments
-  - Add build environment management to CI
-  - Implement automated testing and validation
-
-#### **3.2 Advanced Features**
-- **Goal**: Add advanced features for production use
-- **Implementation**:
-  - Implement build environment snapshots
-  - Add debugging and troubleshooting tools
-  - Create comprehensive monitoring and logging
-
-## Technical Implementation
-
-### **1. Mock Stage Implementation**
-
-Create a new `org.osbuild.deb-mock` stage:
-
-```python
-# stages/org.osbuild.deb-mock.py
-def main(tree, options):
-    """Main function for deb-mock stage"""
-    config = options.get("config", {})
-    environment = options.get("environment", "debian-trixie")
-    arch = options.get("arch", "amd64")
-    
-    # Create mock environment
-    mock_env = create_mock_environment(environment, arch, config)
-    
-    # Install build dependencies
-    install_build_dependencies(mock_env, options.get("packages", []))
-    
-    # Execute build commands
-    execute_build_commands(mock_env, options.get("commands", []))
-    
-    # Collect artifacts
-    collect_artifacts(mock_env, tree)
-    
-    return 0
-```
-
-### **2. Configuration Integration**
-
-Extend debian-forge manifests to support mock configuration:
-
-```json
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.deb-mock",
-          "options": {
-            "environment": "debian-trixie",
-            "arch": "amd64",
-            "config": {
-              "mirror": "http://deb.debian.org/debian",
-              "components": ["main", "contrib", "non-free"]
-            },
-            "packages": [
-              "build-essential",
-              "devscripts",
-              "debhelper"
-            ]
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": ["linux-image-amd64", "systemd"],
-            "mock_environment": true
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-### **3. Mock Environment Management**
-
-Implement mock environment lifecycle management:
-
-```python
-class MockEnvironmentManager:
-    def __init__(self, config):
-        self.config = config
-        self.environments = {}
-    
-    def create_environment(self, name, arch, suite):
-        """Create a new mock environment"""
-        # Implementation using deb-mock API
-        
-    def install_packages(self, env_name, packages):
-        """Install packages in mock environment"""
-        # Implementation using deb-mock package manager
-        
-    def execute_command(self, env_name, command):
-        """Execute command in mock environment"""
-        # Implementation using deb-mock command executor
-        
-    def collect_artifacts(self, env_name, output_dir):
-        """Collect build artifacts from mock environment"""
-        # Implementation using deb-mock artifact collection
-```
-
-## Integration Benefits
-
-### **1. Enhanced Isolation**
-- **Clean Build Environments**: Each build gets a fresh, isolated environment
-- **Dependency Management**: Automatic handling of build dependencies
-- **Security**: Sandboxed builds prevent host system contamination
-
-### **2. Improved Reproducibility**
-- **Consistent Environments**: Identical build environments across different systems
-- **Version Control**: Mock environments can be versioned and managed
-- **Debugging**: Easier debugging with isolated, reproducible environments
-
-### **3. Better Performance**
-- **Environment Caching**: Reuse mock environments for faster builds
-- **Parallel Builds**: Support for multiple concurrent builds
-- **Optimized Dependencies**: Efficient package installation and management
-
-### **4. Production Readiness**
-- **CI/CD Integration**: Seamless integration with automated build systems
-- **Monitoring**: Built-in monitoring and logging capabilities
-- **Scalability**: Support for large-scale build operations
-
-## Migration Strategy
-
-### **Phase 1: Parallel Development**
-- Continue developing debian-forge independently
-- Develop mock integration in parallel
-- Maintain compatibility with existing functionality
-
-### **Phase 2: Integration Testing**
-- Create integration test suite
-- Test mock integration with existing manifests
-- Validate performance and functionality
-
-### **Phase 3: Gradual Migration**
-- Add mock support as optional feature
-- Migrate existing workflows to use mock environments
-- Deprecate non-mock builds over time
-
-## Success Criteria
-
-### **Technical Goals**
-- [ ] Mock environments successfully provisioned for debian-forge builds
-- [ ] All existing APT stages work within mock environments
-- [ ] Build performance improved through environment caching
-- [ ] Cross-architecture builds supported through mock
-
-### **Integration Goals**
-- [ ] Seamless integration with existing debian-forge workflows
-- [ ] CI/CD pipeline updated to use mock environments
-- [ ] Comprehensive documentation for mock integration
-- [ ] User migration guide and examples
-
-### **Production Goals**
-- [ ] Production-ready mock integration
-- [ ] Performance benchmarks showing improvement
-- [ ] Comprehensive testing and validation
-- [ ] Community adoption and feedback
-
-## Implementation Responsibilities
-
-### **debian-forge Project Tasks** ✅ **COMPLETED** / 🔄 **IN PROGRESS** / ❌ **PENDING**
-
-#### **Phase 1: Basic Integration (Weeks 1-4)**
-
-##### **debian-forge Responsibilities:**
-- [x] **Integration Plan** - Comprehensive integration plan documented
-- [x] **Architecture Design** - Clear integration architecture defined
-- [ ] **Mock Stage Implementation** - Create `org.osbuild.deb-mock` stage
-  - [ ] Create `stages/org.osbuild.deb-mock.py` with basic functionality
-  - [ ] Implement mock environment provisioning interface
-  - [ ] Add configuration mapping between debian-forge and deb-mock
-  - [ ] Create mock environment lifecycle management class
-- [ ] **APT Stage Modification** - Modify existing APT stages for mock compatibility
-  - [ ] Update `org.osbuild.apt` stage to work within mock chroots
-  - [ ] Modify `org.osbuild.apt.config` stage for mock environments
-  - [ ] Update `org.osbuild.debootstrap` stage for mock integration
-  - [ ] Add environment variable and mount point management
-- [ ] **Basic Testing** - Create integration test framework
-  - [ ] Create integration test manifests for mock environments
-  - [ ] Test simple Debian image builds with mock
-  - [ ] Validate artifact collection and output from mock
-
-##### **deb-mock Project Dependencies:**
-- [ ] **Python API** - Stable Python API for integration
-- [ ] **Environment Management** - Chroot environment creation and management
-- [ ] **Package Installation** - Package installation within mock environments
-- [ ] **Command Execution** - Command execution within mock chroots
-- [ ] **Artifact Collection** - Artifact collection from mock environments
-
-#### **Phase 2: Advanced Integration (Weeks 5-8)**
-
-##### **debian-forge Responsibilities:**
-- [ ] **Plugin System Integration** - Integrate with deb-mock's plugin system
-  - [ ] Create debian-forge specific plugins for mock
-  - [ ] Implement caching and optimization plugins
-  - [ ] Add plugin configuration management
-- [ ] **Multi-Environment Support** - Support multiple Debian distributions
-  - [ ] Extend mock configuration for different Debian suites
-  - [ ] Add cross-architecture build support through mock
-  - [ ] Implement environment-specific optimizations
-- [ ] **Performance Optimization** - Optimize build performance
-  - [ ] Implement build environment caching
-  - [ ] Add parallel build support with mock
-  - [ ] Optimize package installation and dependency resolution
-
-##### **deb-mock Project Dependencies:**
-- [ ] **Plugin Architecture** - Stable plugin system for extensions
-- [ ] **Multi-Environment Support** - Support for different Debian suites
-- [ ] **Cross-Architecture Support** - ARM64, amd64, etc. support
-- [ ] **Caching System** - Environment caching and reuse
-- [ ] **Parallel Execution** - Parallel environment management
-
-#### **Phase 3: Production Integration (Weeks 9-12)**
-
-##### **debian-forge Responsibilities:**
-- [ ] **CI/CD Integration** - Update CI workflows for mock
-  - [ ] Update Forgejo CI workflows to use mock environments
-  - [ ] Add build environment management to CI
-  - [ ] Implement automated testing and validation
-- [ ] **Advanced Features** - Production-ready features
-  - [ ] Implement build environment snapshots
-  - [ ] Add debugging and troubleshooting tools
-  - [ ] Create comprehensive monitoring and logging
-
-##### **deb-mock Project Dependencies:**
-- [ ] **Production Stability** - Production-ready stability and reliability
-- [ ] **Monitoring Support** - Built-in monitoring and logging capabilities
-- [ ] **Debugging Tools** - Debugging and troubleshooting support
-- [ ] **Documentation** - Comprehensive API documentation
-
-## Current Status Summary
-
-### **debian-forge Project Status:**
-- ✅ **Planning Complete** - Integration plan and architecture designed
-- ✅ **Documentation Complete** - Comprehensive integration documentation
-- ❌ **Implementation Pending** - Mock stage and integration code needed
-- ❌ **Testing Pending** - Integration test framework needed
-
-### **deb-mock Project Status:**
-- 🔄 **Foundation Development** - Currently in Phase 1 development
-- ❌ **API Stability Pending** - Python API needs to be stable for integration
-- ❌ **Production Readiness Pending** - Needs to reach production-ready state
-- ❌ **Integration Support Pending** - Integration features need to be implemented
-
-## Critical Path Dependencies
-
-### **debian-forge Cannot Proceed Without:**
-1. **Stable deb-mock Python API** - Required for mock stage implementation
-2. **Environment Management API** - Required for chroot environment creation
-3. **Command Execution API** - Required for running debian-forge stages in mock
-4. **Artifact Collection API** - Required for collecting build outputs
-
-### **deb-mock Project Priority Items:**
-1. **Python API Development** - Create stable Python API for integration
-2. **Environment Management** - Implement chroot environment lifecycle
-3. **Command Execution** - Add command execution within mock environments
-4. **Documentation** - Provide comprehensive API documentation
-
-## Recommended Next Steps
-
-### **For debian-forge Project:**
-1. **Wait for deb-mock API** - Monitor deb-mock development for stable API
-2. **Create Mock Stage Skeleton** - Create basic mock stage structure
-3. **Design Integration Tests** - Create test framework for mock integration
-4. **Document Integration Requirements** - Document specific API requirements
-
-### **For deb-mock Project:**
-1. **Prioritize Python API** - Focus on stable Python API for integration
-2. **Implement Environment Management** - Add chroot environment lifecycle
-3. **Add Command Execution** - Implement command execution within mock
-4. **Create Integration Examples** - Provide examples for debian-forge integration
-
-## Success Criteria
-
-### **debian-forge Integration Complete When:**
-- [ ] Mock stage successfully provisions deb-mock environments
-- [ ] All APT stages work within mock environments
-- [ ] Build performance improved through environment caching
-- [ ] CI/CD pipeline uses mock environments
-- [ ] Comprehensive testing validates integration
-
-### **deb-mock Project Ready When:**
-- [ ] Stable Python API available
-- [ ] Environment management fully implemented
-- [ ] Command execution working reliably
-- [ ] Production-ready stability achieved
-- [ ] Comprehensive documentation available
-
-This integration requires coordinated development between both projects, with deb-mock providing the foundation infrastructure and debian-forge implementing the integration layer.

docs/mock-package-dependency-issue.md

@@ -1,164 +0,0 @@
-# Mock Package Dependency Issue
-
-## 🚨 **Issue Summary**
-
-The `mock` package (formerly `deb-mock`) has a dependency issue that prevents installation in the current Debian Trixie environment.
-
-## 🔍 **Problem Details**
-
-### **Dependency Chain**
-```
-mock → mock-filesystem → shadow-utils (NOT AVAILABLE)
-```
-
-### **Root Cause**
-- `mock-filesystem` depends on `shadow-utils`
-- `shadow-utils` package is not available in the Debian Trixie repository
-- `passwd` package is available and provides the same functionality
-
-### **Error Message**
-```
-Unsatisfied dependencies:
- mock-filesystem : Depends: shadow-utils but it is not installable
-Error: Unable to correct problems, you have held broken packages.
-```
-
-## 🔧 **Available Alternatives**
-
-### **What's Available**
-```bash
-$ apt-cache search shadow | grep -E "(shadow|passwd|useradd|groupadd)"
-passwd - change and administer password and group data
-liblinux-usermod-perl - module to modify user and group accounts
-libnss-extrausers - nss module to have an additional passwd, shadow and group file
-libpasswd-unix-perl - object-oriented and function interface to standard Unix files
-```
-
-### **What's Missing**
-- `shadow-utils` package is not available in Debian Trixie
-- This package typically provides: `useradd`, `groupadd`, `usermod`, `groupmod`, `userdel`, `groupdel`
-
-## 🛠️ **Proposed Solutions**
-
-### **Solution 1: Update Package Dependencies**
-Update `mock-filesystem` to depend on `passwd` instead of `shadow-utils`:
-
-```diff
-- Depends: shadow-utils
-+ Depends: passwd
-```
-
-### **Solution 2: Make Dependencies Optional**
-Make the shadow utilities dependency optional:
-
-```diff
-- Depends: shadow-utils
-+ Depends: passwd | shadow-utils
-```
-
-### **Solution 3: Remove Dependency**
-If shadow utilities aren't actually required for filesystem layout:
-
-```diff
-- Depends: shadow-utils
-+ # Remove this line entirely
-```
-
-## 🧪 **Verification Steps**
-
-### **Check Current System**
-```bash
-# Check what shadow utilities are available
-$ which useradd groupadd usermod groupmod userdel groupdel
-/usr/sbin/useradd
-/usr/sbin/groupadd
-/usr/sbin/usermod
-/usr/sbin/groupmod
-/usr/sbin/userdel
-/usr/sbin/groupdel
-
-# Check which package provides them
-$ dpkg -S /usr/sbin/useradd
-passwd: /usr/sbin/useradd
-```
-
-### **Test Mock Functionality**
-Once the dependency is fixed, test that mock works correctly:
-
-```bash
-# Install mock
-$ sudo apt install mock
-
-# Test basic functionality
-$ mock --help
-$ mock --version
-```
-
-## 📋 **Action Items**
-
-### **For deb-mock Team**
-1. **Update `mock-filesystem` package** to depend on `passwd` instead of `shadow-utils`
-2. **Test the updated package** in a clean Debian Trixie environment
-3. **Publish the fixed package** to the repository
-4. **Update package metadata** to reflect the correct dependencies
-
-### **For debian-forge Team**
-1. **Document the issue** (this document)
-2. **Test integration** once the package is fixed
-3. **Update documentation** with working installation instructions
-4. **Deploy to production** once mock is available
-
-## 🎯 **Expected Outcome**
-
-Once the dependency issue is resolved:
-
-1. **Mock Installation** - `sudo apt install mock` should work
-2. **Full Integration Testing** - Complete test suite execution
-3. **Production Deployment** - debian-forge mock integration ready
-4. **User Experience** - Seamless mock environment creation
-
-## 📞 **Contact Information**
-
-- **Package Maintainer**: Deb-Mock Team <deb-mock@raines.xyz>
-- **Repository**: https://git.raines.xyz/robojerk/deb-mock
-- **Issue Tracker**: [To be created]
-
-## 📊 **Impact Assessment**
-
-### **Current Impact**
-- **Mock Integration**: Blocked (cannot install mock package)
-- **debian-forge**: Mock features unavailable
-- **User Experience**: Mock functionality not accessible
-
-### **After Fix**
-- **Mock Integration**: Fully functional
-- **debian-forge**: Complete mock support
-- **User Experience**: Full mock environment capabilities
-
-## 🚀 **Timeline**
-
-### **Immediate (Today)**
-- [x] Document the issue
-- [x] Identify root cause
-- [x] Propose solutions
-
-### **Short Term (1-2 days)**
-- [ ] deb-mock team fixes package dependency
-- [ ] Updated package published to repository
-- [ ] debian-forge team tests integration
-
-### **Medium Term (1 week)**
-- [ ] Full integration testing completed
-- [ ] Production deployment ready
-- [ ] User documentation updated
-
-## 📝 **Notes**
-
-- The `passwd` package provides all the shadow utilities that `shadow-utils` would provide
-- This is a common issue when packages are built for different distributions
-- The fix should be straightforward - just update the dependency declaration
-- No code changes are needed, just package metadata updates
-
-**Status**: BLOCKED - Waiting for package dependency fix
-**Priority**: HIGH - Blocks mock integration functionality
-**Effort**: LOW - Simple dependency update required

docs/performance-optimization.md

@@ -1,277 +0,0 @@
-# Performance Optimization Guide
-
-This guide covers performance optimization techniques for `debian-forge` builds.
-
-## APT Caching
-
-### Using apt-cacher-ng
-
-The most effective way to speed up builds is using `apt-cacher-ng` as a local proxy:
-
-```bash
-# Install apt-cacher-ng
-sudo apt install apt-cacher-ng
-
-# Start the service
-sudo systemctl start apt-cacher-ng
-
-# Configure in your manifest
-{
-  "type": "org.osbuild.apt",
-  "options": {
-    "packages": ["linux-image-amd64"],
-    "apt_proxy": "http://localhost:3142"
-  }
-}
-```
-
-### Benefits
-
-- **2-3x faster builds** for repeated packages
-- **Reduced bandwidth** usage
-- **Offline capability** for cached packages
-- **Consistent builds** across different environments
-
-## Build Optimization
-
-### 1. Minimal Base Images
-
-Use `minbase` variant for faster debootstrap:
-
-```json
-{
-  "type": "org.osbuild.debootstrap",
-  "options": {
-    "variant": "minbase",
-    "extra_packages": ["apt", "systemd", "bash"]
-  }
-}
-```
-
-### 2. Package Selection
-
-- Use `recommends: false` to avoid unnecessary packages
-- Install only essential packages
-- Use `extra_packages` in debootstrap for core packages
-
-### 3. Repository Configuration
-
-- Use local mirrors when available
-- Configure sources explicitly
-- Use HTTPS for security without significant performance impact
-
-## Parallel Builds
-
-### Multi-Architecture Builds
-
-Build multiple architectures in parallel:
-
-```bash
-# Build amd64 and arm64 simultaneously
-python3 -m osbuild debian-amd64.json --libdir . &
-python3 -m osbuild debian-arm64.json --libdir . &
-wait
-```
-
-### CI/CD Optimization
-
-Use parallel jobs in CI/CD:
-
-```yaml
-strategy:
-  matrix:
-    arch: [amd64, arm64]
-    suite: [trixie, jammy]
-  max-parallel: 4
-```
-
-## Memory Optimization
-
-### 1. Build Environment
-
-- Use sufficient RAM (8GB+ recommended)
-- Enable swap if needed
-- Monitor memory usage during builds
-
-### 2. Package Cache
-
-- Clean package cache regularly
-- Use `apt-get clean` in manifests
-- Monitor disk space usage
-
-## Network Optimization
-
-### 1. Mirror Selection
-
-Choose geographically close mirrors:
-
-```json
-{
-  "type": "org.osbuild.debootstrap",
-  "options": {
-    "mirror": "http://deb.debian.org/debian"  # Automatic mirror selection
-  }
-}
-```
-
-### 2. Proxy Configuration
-
-Use corporate proxies when available:
-
-```json
-{
-  "type": "org.osbuild.apt",
-  "options": {
-    "apt_proxy": "http://proxy.company.com:3142"
-  }
-}
-```
-
-## Build Time Benchmarks
-
-### Typical Build Times
-
-| Image Type | Base Time | With apt-cacher-ng | Improvement |
-|------------|-----------|-------------------|-------------|
-| Minimal Debian | 5-10 min | 2-3 min | 60-70% |
-| Server Image | 10-15 min | 4-6 min | 60-70% |
-| Ubuntu Image | 8-12 min | 3-5 min | 60-70% |
-| ARM64 Build | 15-20 min | 6-8 min | 60-70% |
-
-### Factors Affecting Build Time
-
-1. **Network speed** - Primary factor
-2. **Package count** - Linear relationship
-3. **Architecture** - ARM64 typically slower
-4. **Base image size** - Minimal images faster
-5. **Caching** - Significant improvement with apt-cacher-ng
-
-## Monitoring and Profiling
-
-### Build Logs
-
-Enable detailed logging:
-
-```bash
-python3 -m osbuild manifest.json --json | jq '.log'
-```
-
-### Stage Timing
-
-Monitor individual stage performance:
-
-```bash
-python3 -m osbuild manifest.json --monitor timing
-```
-
-### Resource Usage
-
-Monitor system resources during builds:
-
-```bash
-# Monitor CPU and memory
-htop
-
-# Monitor disk I/O
-iotop
-
-# Monitor network
-nethogs
-```
-
-## Troubleshooting Performance Issues
-
-### Slow Package Downloads
-
-1. Check network connectivity
-2. Use apt-cacher-ng
-3. Try different mirrors
-4. Check for network throttling
-
-### High Memory Usage
-
-1. Increase available RAM
-2. Enable swap
-3. Reduce package count
-4. Use minimal base images
-
-### Disk Space Issues
-
-1. Clean package cache
-2. Remove old build artifacts
-3. Use external storage for builds
-4. Monitor disk usage
-
-## Best Practices
-
-### 1. Development Workflow
-
-- Use apt-cacher-ng for all builds
-- Keep manifests minimal and focused
-- Test with different architectures
-- Monitor build performance regularly
-
-### 2. CI/CD Optimization
-
-- Use parallel builds when possible
-- Cache APT packages between builds
-- Use minimal base images
-- Monitor build times and resources
-
-### 3. Production Builds
-
-- Use dedicated build servers
-- Implement proper caching
-- Monitor and alert on performance
-- Regular cleanup of build artifacts
-
-## Advanced Techniques
-
-### Custom APT Configuration
-
-Optimize APT settings for your environment:
-
-```json
-{
-  "type": "org.osbuild.apt.config",
-  "options": {
-    "config": {
-      "Acquire": {
-        "http": {
-          "Pipeline-Depth": "5"
-        }
-      }
-    }
-  }
-}
-```
-
-### Build Caching
-
-Implement build artifact caching:
-
-```bash
-# Cache build artifacts
-python3 -m osbuild manifest.json --cache ./build-cache
-
-# Reuse cached artifacts
-python3 -m osbuild manifest.json --cache ./build-cache --checkpoint build
-```
-
-### Incremental Builds
-
-Use checkpoints for incremental builds:
-
-```bash
-# Build up to specific stage
-python3 -m osbuild manifest.json --checkpoint org.osbuild.apt
-
-# Continue from checkpoint
-python3 -m osbuild manifest.json --checkpoint org.osbuild.apt
-```
-
-## See Also
-
-- [APT Stages Reference](apt-stages.md)
-- [Debian Image Building Tutorial](debian-image-building-tutorial.md)
-- [Troubleshooting Guide](troubleshooting.md)

error-results/error-handling-report.md

@@ -1,57 +0,0 @@
-# Debian Forge Error Handling Report
-
-Generated: Thu Sep  4 09:00:37 AM PDT 2025
-
-## Test Results
-
-| Test Case | Result | Error Message |
-|-----------|--------|---------------|
-| invalid-manifest | ❌ FAIL | JSON parse error |
-| network-failure | ✅ PASS | No error detected |
-| invalid-repository | ✅ PASS | No error detected |
-| missing-packages | ✅ PASS | No error detected |
-
-## Error Analysis
-
-### JSON Validation Errors
-- **Invalid manifest**: Should fail with JSON schema validation error
-- **Expected behavior**: Clear error message about malformed JSON
-
-### Package Resolution Errors
-- **Missing packages**: Should fail with package not found error
-- **Expected behavior**: Clear error message about missing packages
-
-### Network Errors
-- **Invalid repository**: Should fail with network/connection error
-- **Expected behavior**: Clear error message about repository access
-
-### Recovery Recommendations
-
-1. **JSON Validation**
-   - Implement better JSON schema validation
-   - Provide clear error messages for malformed manifests
-   - Add manifest validation tools
-
-2. **Package Resolution**
-   - Improve package not found error messages
-   - Add package availability checking
-   - Implement package suggestion system
-
-3. **Network Errors**
-   - Add network connectivity checks
-   - Implement retry mechanisms
-   - Provide fallback repository options
-
-4. **General Error Handling**
-   - Add error recovery mechanisms
-   - Implement graceful degradation
-   - Provide detailed error logging
-
-## Next Steps
-
-1. Implement comprehensive error handling
-2. Add error recovery mechanisms
-3. Improve error messages
-4. Add validation tools
-5. Implement retry logic
-

error-results/invalid-manifest_result.json

@@ -1,24 +0,0 @@
-Traceback (most recent call last):
-  File "<frozen runpy>", line 198, in _run_module_as_main
-  File "<frozen runpy>", line 88, in _run_code
-  File "/home/joe/Projects/overseer/debian-forge/osbuild/__main__.py", line 12, in <module>
-    r = main()
-  File "/home/joe/Projects/overseer/debian-forge/osbuild/main_cli.py", line 115, in osbuild_cli
-    desc = parse_manifest(args.manifest_path)
-  File "/home/joe/Projects/overseer/debian-forge/osbuild/main_cli.py", line 31, in parse_manifest
-    manifest = json.load(f)
-  File "/usr/lib/python3.13/json/__init__.py", line 293, in load
-    return loads(fp.read(),
-        cls=cls, object_hook=object_hook,
-        parse_float=parse_float, parse_int=parse_int,
-        parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, **kw)
-  File "/usr/lib/python3.13/json/__init__.py", line 346, in loads
-    return _default_decoder.decode(s)
-           ~~~~~~~~~~~~~~~~~~~~~~~^^^
-  File "/usr/lib/python3.13/json/decoder.py", line 345, in decode
-    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
-               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
-  File "/usr/lib/python3.13/json/decoder.py", line 361, in raw_decode
-    obj, end = self.scan_once(s, idx)
-               ~~~~~~~~~~~~~~^^^^^^^^
-json.decoder.JSONDecodeError: Expecting ',' delimiter: line 19 column 3 (char 354)

error-results/invalid-repository_result.json

@@ -1 +0,0 @@
-{"type": "result", "success": true, "metadata": {}, "log": {}}

error-results/missing-packages_result.json

@@ -1 +0,0 @@
-{"type": "result", "success": true, "metadata": {}, "log": {}}

error-results/network-failure_result.json

@@ -1 +0,0 @@
-{"type": "result", "success": true, "metadata": {}, "log": {}}

error-tests/invalid-manifest.json

@@ -1,20 +0,0 @@
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64"
-          }
-        }
-      ]
-    }
-  ]
-  // Missing closing brace - invalid JSON
-}

error-tests/invalid-repository.json

@@ -1,19 +0,0 @@
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://invalid-mirror-that-does-not-exist.com/debian",
-            "arch": "amd64"
-          }
-        }
-      ]
-    }
-  ]
-}

error-tests/missing-packages.json

@@ -1,28 +0,0 @@
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://deb.debian.org/debian",
-            "arch": "amd64"
-          }
-        },
-        {
-          "type": "org.osbuild.apt",
-          "options": {
-            "packages": [
-              "nonexistent-package-12345",
-              "another-missing-package-67890"
-            ]
-          }
-        }
-      ]
-    }
-  ]
-}

error-tests/network-failure.json

@@ -1,19 +0,0 @@
-{
-  "version": "2",
-  "pipelines": [
-    {
-      "runner": "org.osbuild.linux",
-      "name": "build",
-      "stages": [
-        {
-          "type": "org.osbuild.debootstrap",
-          "options": {
-            "suite": "trixie",
-            "mirror": "http://192.168.1.999/debian",
-            "arch": "amd64"
-          }
-        }
-      ]
-    }
-  ]
-}

generated_docs/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,147 @@
+# Debian Forge Deployment Guide
+
+*Generated on: 2025-08-23 09:39:21*
+
+## System Requirements
+
+### Hardware Requirements
+- **CPU**: 4 cores minimum, 8+ cores recommended
+- **Memory**: 8GB minimum, 16GB+ recommended
+- **Storage**: 50GB minimum, SSD recommended
+- **Network**: 1Gbps minimum, 10Gbps recommended
+
+### Software Requirements
+- **Operating System**: Debian 12+ (Bookworm)
+- **Kernel**: Linux 5.15+
+- **Python**: 3.8+
+- **Database**: SQLite (default) or PostgreSQL
+
+## Installation
+
+### Prerequisites
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install required packages
+sudo apt install -y python3 python3-pip python3-venv git
+sudo apt install -y build-essential libssl-dev libffi-dev
+
+# Install Go (for CLI and Composer)
+sudo apt install -y golang-go
+```
+
+### Source Installation
+```bash
+# Clone repositories
+git clone <debian-forge-repo>
+git clone <debian-forge-cli-repo>
+git clone <debian-forge-composer-repo>
+
+# Set up Python environment
+cd debian-forge
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+### Environment Configuration
+```bash
+# Create configuration file
+cp config.example.yaml config.yaml
+
+# Edit configuration
+nano config.yaml
+```
+
+### Database Configuration
+- **SQLite**: Default, no additional configuration needed
+- **PostgreSQL**: Configure connection parameters
+- **Database Initialization**: Run setup scripts
+
+### Security Configuration
+- **SSL/TLS**: Configure HTTPS certificates
+- **Firewall**: Configure network security
+- **User Authentication**: Set up initial admin user
+
+## Service Configuration
+
+### Systemd Service
+```ini
+[Unit]
+Description=Debian Forge Service
+After=network.target
+
+[Service]
+Type=simple
+User=debian-forge
+WorkingDirectory=/opt/debian-forge
+ExecStart=/opt/debian-forge/venv/bin/python main.py
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Nginx Configuration
+```nginx
+server {
+    listen 80;
+    server_name debian-forge.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    server_name debian-forge.example.com;
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+## Deployment Steps
+
+### 1. System Preparation
+- Verify system requirements
+- Install prerequisites
+- Configure system settings
+
+### 2. Application Installation
+- Clone source repositories
+- Install dependencies
+- Configure application
+
+### 3. Service Setup
+- Create system user
+- Configure systemd service
+- Set up reverse proxy
+
+### 4. Initial Configuration
+- Initialize database
+- Create admin user
+- Configure security settings
+
+### 5. Testing and Validation
+- Test service startup
+- Verify web interface
+- Test basic functionality
+
+## Monitoring and Maintenance
+
+### Health Checks
+- **Service Status**: Check systemd service status
+- **Web Interface**: Verify web interface accessibility
+- **Database Health**: Check database connectivity
+- **Performance Metrics**: Monitor system performance
+
+### Backup Procedures
+- **Configuration Files**: Backup configuration directory
+- **Database**: Regular database backups
+- **User Data**: Backup user uploads and generated images

generated_docs/MAINTENANCE_GUIDE.md

@@ -0,0 +1,125 @@
+# Debian Forge Maintenance Guide
+
+*Generated on: 2025-08-23 09:39:21*
+
+## Regular Maintenance Tasks
+
+### Daily Tasks
+- **System Health Check**: Verify all services are running
+- **Performance Monitoring**: Review performance metrics
+- **Error Log Review**: Check for new error messages
+- **Backup Verification**: Ensure backups completed successfully
+
+### Weekly Tasks
+- **Performance Analysis**: Review weekly performance trends
+- **Security Audit**: Run security vulnerability scans
+- **Database Maintenance**: Clean up old data and optimize
+- **Log Rotation**: Rotate and compress log files
+
+### Monthly Tasks
+- **System Updates**: Apply security and feature updates
+- **Capacity Planning**: Review resource usage trends
+- **Security Review**: Update security configurations
+- **Documentation Review**: Update operational procedures
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Service Won't Start
+1. Check systemd service status: `systemctl status debian-forge`
+2. Review service logs: `journalctl -u debian-forge`
+3. Verify configuration files
+4. Check file permissions and ownership
+
+#### Performance Issues
+1. Monitor system resources: `htop`, `iotop`
+2. Check database performance
+3. Review build queue length
+4. Analyze performance metrics
+
+#### Authentication Problems
+1. Verify user database integrity
+2. Check password policies
+3. Review authentication logs
+4. Test user login process
+
+## Backup and Recovery
+
+### Backup Procedures
+
+#### Configuration Backup
+```bash
+# Backup configuration directory
+tar -czf config-backup-$(date +%Y%m%d).tar.gz config/
+
+# Backup database files
+cp *.db backup/
+```
+
+#### Database Backup
+```bash
+# SQLite backup
+sqlite3 users.db .dump > backup/users-$(date +%Y%m%d).sql
+
+# PostgreSQL backup
+pg_dump debian_forge > backup/postgres-$(date +%Y%m%d).sql
+```
+
+### Recovery Procedures
+
+#### Configuration Recovery
+1. Stop the service: `systemctl stop debian-forge`
+2. Restore configuration files
+3. Verify file permissions
+4. Start the service: `systemctl start debian-forge`
+
+#### Database Recovery
+1. Stop the service
+2. Restore database from backup
+3. Verify database integrity
+4. Start the service
+
+## Performance Optimization
+
+### System Tuning
+- **CPU Optimization**: Adjust process priorities
+- **Memory Management**: Configure swap and memory limits
+- **Disk I/O**: Optimize storage configuration
+- **Network Tuning**: Optimize network parameters
+
+### Application Tuning
+- **Database Optimization**: Index optimization and query tuning
+- **Build Optimization**: Parallel build processing
+- **Cache Management**: Implement and tune caching
+- **Resource Pooling**: Optimize resource allocation
+
+## Security Maintenance
+
+### Regular Security Tasks
+- **Vulnerability Scanning**: Run security audits
+- **Access Review**: Review user access and permissions
+- **Security Updates**: Apply security patches
+- **Configuration Review**: Review security settings
+
+### Incident Response
+1. **Detection**: Identify security incidents
+2. **Assessment**: Evaluate incident severity
+3. **Containment**: Limit incident impact
+4. **Eradication**: Remove security threats
+5. **Recovery**: Restore normal operations
+6. **Lessons Learned**: Document and improve procedures
+
+## Monitoring and Alerting
+
+### Key Metrics to Monitor
+- **System Resources**: CPU, memory, disk, network
+- **Application Performance**: Response times, throughput
+- **Build Queue**: Queue length, processing times
+- **Security Events**: Authentication failures, access attempts
+
+### Alerting Configuration
+- **Threshold Alerts**: Resource usage alerts
+- **Performance Alerts**: Response time and error rate alerts
+- **Security Alerts**: Security incident notifications
+- **Service Alerts**: Service availability notifications

generated_docs/README.md

@@ -0,0 +1,36 @@
+# Debian Forge Documentation Index
+
+*Generated on: 2025-08-23 09:39:21*
+
+## Documentation Overview
+
+This directory contains comprehensive documentation for the Debian Forge project.
+
+## Available Documentation
+
+### 📚 [Technical Documentation](TECHNICAL_DOCUMENTATION.md)
+Comprehensive technical reference including architecture, API documentation, and system specifications.
+
+### 📖 [User Guide](USER_GUIDE.md)
+User-friendly guide for using Debian Forge, including getting started, blueprint creation, and troubleshooting.
+
+### 🚀 [Deployment Guide](DEPLOYMENT_GUIDE.md)
+Step-by-step deployment instructions, system requirements, and configuration details.
+
+### 🔧 [Maintenance Guide](MAINTENANCE_GUIDE.md)
+Operational procedures, troubleshooting guides, and maintenance best practices.
+
+## Quick Start
+
+1. **New Users**: Start with the [User Guide](USER_GUIDE.md)
+2. **System Administrators**: Review the [Deployment Guide](DEPLOYMENT_GUIDE.md)
+3. **Developers**: Reference the [Technical Documentation](TECHNICAL_DOCUMENTATION.md)
+4. **Operations**: Use the [Maintenance Guide](MAINTENANCE_GUIDE.md)
+
+## Documentation Maintenance
+
+This documentation is automatically generated and should be updated when:
+- New features are added to the system
+- Configuration options change
+- Security procedures are updated
+- Deployment processes are modified