Document all working commands and validation methods
- Created WORKING_COMMANDS.md with comprehensive command documentation - Added validate-image command to justfile (bootc container lint) - Added check-image-labels command to justfile (OSTree validation) - Added test-via-loopback command to justfile (working deployment method) - Updated help documentation with new commands - Documented critical environment variables and requirements - Recorded all tested and validated commands for future reference All commands have been tested and validated throughout the project.
This commit is contained in:
robojerk
parent
339adfae95
commit
4a70ed728c
2 changed files with 350 additions and 0 deletions
|
|
@ -213,6 +213,29 @@ test-bootc-info:
|
|||
podman run --rm localhost/debian-atomic:latest \
|
||||
bash -c "bootc --version && bootc --help"
|
||||
|
||||
# Validate image with bootc container lint (CRITICAL)
|
||||
validate-image:
|
||||
@echo "Validating image with bootc container lint..."
|
||||
podman run --rm localhost/debian-atomic:latest \
|
||||
bash -c "bootc container lint"
|
||||
|
||||
# Check image labels and OSTree configuration
|
||||
check-image-labels:
|
||||
@echo "Checking image labels and OSTree configuration..."
|
||||
podman inspect localhost/debian-atomic:latest | grep -A 10 -B 10 ostree
|
||||
|
||||
# Test via-loopback deployment (working method)
|
||||
test-via-loopback:
|
||||
@echo "Testing via-loopback deployment..."
|
||||
qemu-img create -f raw test-loopback.img 10G
|
||||
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
|
||||
podman run --rm --privileged --pid=host --volume /dev:/dev \
|
||||
--volume .:/work --env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
|
||||
--env LANG=C.UTF-8 --env LC_ALL=C.UTF-8 --workdir /work \
|
||||
localhost/debian-atomic:latest \
|
||||
/usr/bin/bootc install to-disk --via-loopback test-loopback.img --filesystem ext4 --wipe
|
||||
rm -f test-loopback.img
|
||||
|
||||
# Clean up all test files
|
||||
clean-test-files:
|
||||
@echo "Cleaning up test files..."
|
||||
|
|
@ -257,6 +280,9 @@ help:
|
|||
@echo " just verify-disk-utils - Verify disk utilities in container"
|
||||
@echo " just check-kernel-files - Check kernel files in container"
|
||||
@echo " just test-bootc-info - Test bootc info commands"
|
||||
@echo " just validate-image - Validate image with bootc container lint"
|
||||
@echo " just check-image-labels - Check image labels and OSTree configuration"
|
||||
@echo " just test-via-loopback - Test via-loopback deployment (working method)"
|
||||
@echo " Utility commands:"
|
||||
@echo " just list-images - List all debian-atomic images"
|
||||
@echo " just inspect-image - Show image details"
|
||||
|
|
|
|||
324
WORKING_COMMANDS.md
Normal file
324
WORKING_COMMANDS.md
Normal file
|
|
@ -0,0 +1,324 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue