Particle-OS Simple-CLI

Overview

Particle-OS Simple-CLI is a development and testing environment that demonstrates the core Particle-OS concepts working together. It inherits directly from the Debian Atomic foundation and integrates all three core Particle-OS tools:

• apt-ostree: Atomic package management
• bootupd: Bootloader update management
• bootc: Container deployment and management

Architecture

Debian Atomic (proven foundation)
    ↓
Particle-OS Simple-CLI
    ↓
Integrated tools: apt-ostree + bootupd + bootc

Features

• ✅ Clean Architecture: Direct inheritance from Debian Atomic
• ✅ Tool Integration: All three Particle-OS tools working together
• ✅ Concept Proofing: Atomic update workflow demonstrated
• ✅ SSH Access: Remote access configured and ready
• ✅ OSTree Foundation: Full OSTree system with all features

Quick Start

Build the Container

just build-with-tools-ssh

Test the Integration

just test

Run the Demo

./demo-concepts.sh

Available Commands

• verify-tools - Verify all Particle-OS tools are available
• simple-cli-welcome - Show welcome message and available commands
• demo-concepts.sh - Demonstrate all tools working together

Tool Status

Tool	Status	Version	Notes
apt-ostree	✅ Working	0.1.0	1,470 packages available
bootupd	✅ Working	0.2.28	EFI components detected
bootc	✅ Working	1.6.0	Container deployment ready
OSTree	✅ Working	2025.2	Full feature set

Testing

Basic Functionality Test

podman run --rm simple-cli:latest /usr/local/bin/verify-tools

Concept Demonstration

podman run --rm simple-cli:latest bash -c "apt-ostree list | head -5"
podman run --rm simple-cli:latest bash -c "bootupctl status"
podman run --rm simple-clI:latest bash -c "bootc --help"

Development

Project Structure

simple-cli/
├── Containerfile          # Container definition
├── justfile              # Build automation
├── tools/                # Integrated .deb packages
├── demo-concepts.sh      # Concept demonstration
├── README.md             # This file
└── output/               # Generated outputs

Build Recipes

• just build-with-tools-ssh - Build with SSH and tools
• just test - Test the built container
• just clean - Clean build artifacts

Integration Status

What's Working

• ✅ All three Particle-OS tools integrated
• ✅ Tools can communicate and work together
• ✅ OSTree foundation fully functional
• ✅ SSH server configured and ready
• ✅ Clean architecture proven

What's Next

• 🚧 Bootable image creation (technical challenges)
• 🚧 QEMU testing and validation
• 🚧 End-to-end atomic update workflow
• 🚧 Production deployment

Troubleshooting

Common Issues

1. Container registry issues: Use full image IDs instead of short names
2. Permission issues: Run with --privileged flag when needed
3. Storage access: Mount volumes explicitly for file access

Debug Commands

# Check tool availability
podman run --rm simple-cli:latest which bootc

# Verify OSTree status
podman run --rm simple-cli:latest ostree --version

# Test package management
podman run --rm simple-cli:latest apt-ostree list | head -10

Contributing

This project demonstrates the core Particle-OS concepts. To contribute:

1. Test the integration with different tool combinations
2. Improve the demonstration scripts
3. Add new testing scenarios
4. Document any discovered issues or solutions

License

Part of the Particle-OS project - Debian-based immutable operating system.