deb-bootc-image-builder/docs/DEBOS_ENVIRONMENT_SETUP.md

Debos Environment Setup Guide

🎯 Overview

This guide provides step-by-step instructions for setting up a proper debos environment to test the complete end-to-end workflow of deb-bootc-image-builder. The goal is to create an environment where debos can successfully execute and generate bootable images.

🔧 Prerequisites

System Requirements

• OS: Debian 12+ (Bookworm) or Ubuntu 22.04+ (Jammy)
• Architecture: x86_64 (amd64)
• RAM: Minimum 4GB, recommended 8GB+
• Disk Space: At least 10GB free space
• Permissions: Root access or sudo privileges

Required Tools

• debos: Debian image building tool
• fakemachine: Virtual machine environment for debos
• podman/docker: Container runtime
• qemu-img: QEMU image manipulation tool
• tar: Archive manipulation tool

📦 Installation Steps

Step 1: Update System

sudo apt update
sudo apt upgrade -y

Step 2: Install Required Packages

# Core debos and fakemachine
sudo apt install -y debos fakemachine

# Container runtime (podman preferred, docker as fallback)
sudo apt install -y podman

# QEMU tools for image manipulation
sudo apt install -y qemu-utils

# Additional dependencies
sudo apt install -y tar gzip squashfs-tools

Step 3: Verify Installation

# Check debos version
debos --version

# Check fakemachine
fakemachine --help

# Check podman
podman --version

# Check qemu-img
qemu-img --version

🐳 Container Runtime Setup

Podman Configuration (Recommended)

# Enable podman socket for rootless operation
sudo systemctl enable --now podman.socket

# Test podman
podman run --rm hello-world

Docker Configuration (Alternative)

# Install Docker if podman is not available
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Test Docker
docker run --rm hello-world

🔐 Permissions and Security

Fakemachine Permissions

# Ensure fakemachine can access required devices
sudo usermod -aG kvm $USER
sudo usermod -aG disk $USER

# Check KVM availability
ls -l /dev/kvm

Directory Permissions

# Create work directories with proper permissions
sudo mkdir -p /var/tmp/debos-work
sudo chown $USER:$USER /var/tmp/debos-work
sudo chmod 755 /var/tmp/debos-work

🧪 Environment Testing

Basic Debos Test

Create a simple test manifest to verify the environment:

# test-simple.yaml
architecture: x86_64
suite: trixie
actions:
  - action: run
    description: Simple test action
    script: |
      #!/bin/bash
      echo "Hello from debos!"
      echo "Environment test successful!"
      echo "Current directory: $(pwd)"
      echo "User: $(whoami)"
      echo "Date: $(date)"

Run Test

# Test with dry-run first
debos --dry-run test-simple.yaml

# If successful, run for real
debos test-simple.yaml

🚀 Advanced Environment Setup

VM-Based Testing Environment

For more reliable testing, consider using a VM:

# Create a test VM with virt-manager or qemu
# Recommended specs:
# - 4GB RAM
# - 20GB disk
# - KVM acceleration enabled
# - Network access for package downloads

Container-Based Testing Environment

# Create a privileged container for testing
sudo podman run -it --privileged \
  -v /var/tmp/debos-work:/work \
  -v /dev:/dev \
  debian:bookworm

# Inside container, install debos and dependencies
apt update
apt install -y debos fakemachine podman qemu-utils

🔍 Troubleshooting

Common Issues and Solutions

1. Fakemachine Permission Errors

# Error: "fakemachine: permission denied"
# Solution: Check KVM and disk group membership
sudo usermod -aG kvm,disk $USER
# Log out and back in, or run: newgrp kvm

2. Debos Execution Failures

# Error: "debos: command not found"
# Solution: Ensure debos is in PATH
which debos
export PATH=$PATH:/usr/local/bin

# Error: "fakemachine not found"
# Solution: Install fakemachine package
sudo apt install -y fakemachine

3. Container Runtime Issues

# Error: "podman: permission denied"
# Solution: Enable podman socket
sudo systemctl enable --now podman.socket

# Error: "docker: permission denied"
# Solution: Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

4. KVM Issues

# Error: "KVM not available"
# Solution: Check KVM module
lsmod | grep kvm
sudo modprobe kvm_intel  # For Intel CPUs
sudo modprobe kvm_amd    # For AMD CPUs

# Check KVM device
ls -l /dev/kvm

Debug Mode

# Run debos with verbose output
debos -v test-manifest.yaml

# Run with debug logging
debos --debug test-manifest.yaml

# Check fakemachine logs
journalctl -u fakemachine

📊 Environment Validation

Validation Script

Use our end-to-end testing program to validate the environment:

# Build and run the end-to-end tester
cd bib
go build -o test-end-to-end-workflow test-end-to-end-workflow.go
./test-end-to-end-workflow

Expected Results

• ✅ Environment validation passes
• ✅ Container extraction works
• ✅ Manifest generation successful
• ✅ Debos execution successful (in proper environment)
• ✅ Image files generated

🎯 Next Steps After Setup

1. Test Complete Workflow

# Test with real container images
./debos-integration-demo

# Test container extraction
./test-container-extraction

2. Validate Generated Images

# Check generated image files
ls -la test-debos-integration/output/

# Validate image format
qemu-img info output-image.qcow2

3. Boot Testing

# Test booting generated images in QEMU
qemu-system-x86_64 \
  -m 2G \
  -enable-kvm \
  -drive file=output-image.qcow2,format=qcow2 \
  -display gtk

📚 Additional Resources

Documentation

• Debos Documentation
• Fakemachine Documentation
• Debian Image Building Guide

Community Support

• Debos GitHub Issues
• Debian Forums
• IRC: #debian-devel on irc.debian.org

---

Last Updated: August 11, 2025
Status: ✅ Environment Setup Guide Complete
Next: Setup proper debos environment and test end-to-end workflow