particle-os/WORKING_COMMANDS.md

Working Commands Documentation - Particle OS

This document records all the working commands we've discovered and tested throughout the Particle OS project. These commands have been validated and are ready for use.

Phase 1: Debian Atomic Base Image

Building the Atomic Image

# Build the atomic image
cd 01-debian-atomic
just build-image

# Alternative: Direct podman build
podman build -t debian-atomic:latest .

Validating the Image

# Run bootc container lint validation (CRITICAL - must pass)
podman run --rm localhost/debian-atomic:latest bash -c "bootc container lint"

# Check image labels and structure
podman inspect localhost/debian-atomic:latest | grep -A 10 -B 10 ostree

# Verify kernel files are present
podman run --rm localhost/debian-atomic:latest bash -c "ls -la /boot/ && ls -la /usr/lib/modules/"

# Check disk utilities availability
podman run --rm localhost/debian-atomic:latest bash -c "which parted && which sfdisk && which mkfs.ext4 && which mkfs.fat && which grub-install"

Testing Disk Operations

# Create test disk image
qemu-img create -f raw test-disk.img 10G

# Test bootc deployment to loop device (with proper PATH and environment)
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  --env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  --env LANG=C.UTF-8 \
  --env LC_ALL=C.UTF-8 \
  localhost/debian-atomic:latest \
  /usr/bin/bootc install to-disk --via-loopback test-disk.img --filesystem ext4 --wipe

# Clean up test files
rm -f test-disk.img

Environment Variables (CRITICAL)

# Required environment variables for bootc operations
export PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin"
export LANG=C.UTF-8
export LC_ALL=C.UTF-8

# Full command with all required environment variables
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  LANG=C.UTF-8 \
  LC_ALL=C.UTF-8 \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  --env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  --env LANG=C.UTF-8 \
  --env LC_ALL=C.UTF-8 \
  localhost/debian-atomic:latest \
  /usr/bin/bootc install to-disk /dev/target-device --filesystem ext4

Phase 2: Installer Development

Terminal Installer (02-installer-bootc-tui/)

# Build the terminal installer
cd 02-installer-bootc-tui
just build-installer

# Create bootable ISO
just create-iso

# Test the installer in QEMU
just test-installer-qemu

# Full workflow test
just test-full-workflow

Bootc Installer (02-installer-bootc/)

# Build the bootc installer
cd 02-installer-bootc
just build-installer

# Test with systemd
just test-installer-systemd

# Create ISO
just create-iso

Container Management

Image Operations

# List images with digests
podman images --digests

# Remove images
podman rmi localhost/debian-atomic:latest

# Clean all images
podman system prune -a -f

# Save image to tar file
podman save -o debian-atomic.tar localhost/debian-atomic:latest

# Load image from tar file
podman load -i debian-atomic.tar

Container Operations

# Run container interactively
podman run --rm -it localhost/debian-atomic:latest /bin/bash

# Run container with specific command
podman run --rm localhost/debian-atomic:latest /usr/bin/bootc --version

# Run container with volume mounts
podman run --rm --volume .:/work --workdir /work localhost/debian-atomic:latest /bin/bash

Disk Utility Verification

Host System Verification

# Check if required disk utilities are installed
which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr

# Install missing utilities (if needed)
sudo apt update
sudo apt install -y util-linux parted e2fsprogs dosfstools grub-efi-amd64 efibootmgr

# Verify sfdisk functionality
sfdisk --version

Container Verification

# Verify disk utilities in container
podman run --rm localhost/debian-atomic:latest bash -c "
which parted && parted --version && \
which sfdisk && sfdisk --version && \
which mkfs.ext4 && mkfs.ext4 -V && \
which mkfs.fat && mkfs.fat --help | head -1
"

Testing and Validation

QEMU Testing

# Test ISO in QEMU
qemu-system-x86_64 -cdrom installer.iso -m 2G -enable-kvm

# Test with specific options
qemu-system-x86_64 -cdrom installer.iso -m 4G -smp 2 -enable-kvm -display gtk

Loop Device Testing

# Create loop device for testing
sudo losetup -f test-disk.img
LOOP_DEV=$(sudo losetup -j test-disk.img | cut -d: -f1)

# Use loop device with bootc
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  --env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  localhost/debian-atomic:latest \
  /usr/bin/bootc install to-disk $LOOP_DEV --filesystem ext4

# Clean up loop device
sudo losetup -d $LOOP_DEV

Troubleshooting Commands

Debug Container Issues

# Check container logs
podman logs <container_id>

# Inspect container configuration
podman inspect <container_id>

# Run container with debug shell
podman run --rm -it --entrypoint /bin/bash localhost/debian-atomic:latest

Debug bootc Issues

# Check bootc version
podman run --rm localhost/debian-atomic:latest bash -c "bootc --version"

# Check ostree version
podman run --rm localhost/debian-atomic:latest bash -c "ostree --version"

# Run bootc with verbose output
podman run --rm localhost/debian-atomic:latest bash -c "bootc install to-disk --help"

Debug Image Issues

# Check image labels
podman inspect localhost/debian-atomic:latest | grep -A 5 -B 5 ostree

# Check image layers
podman history localhost/debian-atomic:latest

# Check image size
podman images localhost/debian-atomic:latest

Git Operations

Commit and Push

# Add changes
git add .

# Commit with descriptive message
git commit -m "Phase 1 Complete: Resolve kernel detection and bootc validation issues"

# Push to remote
git push origin main

Clean Up

# Remove test files
rm -f test-*.img
rm -f *.tar

# Clean git
git clean -fd

Performance Optimization

apt-cacher-ng Setup

# Set up apt-cacher-ng
./scripts/setup-apt-cacher.sh

# Use proxy in builds (add to Containerfile)
ENV http_proxy=http://host.containers.internal:3142
ENV https_proxy=http://host.containers.internal:3142

Critical Success Factors

Environment Variables (MUST USE)

# These environment variables are CRITICAL for bootc operations
PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin"
LANG=C.UTF-8
LC_ALL=C.UTF-8

Required Flags for bootc

# These flags are REQUIRED for bootc install to-disk
--privileged
--pid=host
--volume /dev:/dev

Container Prerequisites

# These packages MUST be installed in the container
util-linux    # Provides sfdisk
parted        # Alternative partitioning
e2fsprogs     # Provides mkfs.ext4
dosfstools    # Provides mkfs.fat
grub-efi-amd64
efibootmgr

Notes

• All commands have been tested and validated
• Environment variables are critical for proper operation
• The PATH issue with sfdisk is a common problem in minimal environments
• UTF-8 encoding issues are resolved with proper locale settings
• Kernel detection issues are resolved with proper file placement
• Local image deployment has tool limitations but image is valid

Future Enhancements

• Integrate bootc-image-builder when available in Debian
• Test deployment via container registry
• Add automated testing scripts
• Implement CI/CD pipeline