# 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

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

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

### Validating the Image

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

```bash
# 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)

```bash
# 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/)

```bash
# 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/)

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

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

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

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

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

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

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

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

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

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

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

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

# Clean git
git clean -fd
```

## Performance Optimization

### apt-cacher-ng Setup

```bash
# 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)

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

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

### Container Prerequisites

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