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**
```bash
sudo apt update
sudo apt upgrade -y
```

### **Step 2: Install Required Packages**
```bash
# 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**
```bash
# 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)**
```bash
# Enable podman socket for rootless operation
sudo systemctl enable --now podman.socket

# Test podman
podman run --rm hello-world
```

### **Docker Configuration (Alternative)**
```bash
# 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**
```bash
# 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**
```bash
# 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:

```yaml
# 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**
```bash
# 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:

```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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:

```bash
# 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**
```bash
# Test with real container images
./debos-integration-demo

# Test container extraction
./test-container-extraction
```

### **2. Validate Generated Images**
```bash
# Check generated image files
ls -la test-debos-integration/output/

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

### **3. Boot Testing**
```bash
# 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](https://github.com/go-debos/debos)
- [Fakemachine Documentation](https://github.com/go-debos/fakemachine)
- [Debian Image Building Guide](https://wiki.debian.org/DebianInstaller/ImageBuilding)

### **Community Support**
- [Debos GitHub Issues](https://github.com/go-debos/debos/issues)
- [Debian Forums](https://forums.debian.net/)
- [IRC: #debian-devel on irc.debian.org](irc://irc.debian.org/#debian-devel)

---

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