Add comprehensive documentation, live-build configuration, and testing framework
Some checks failed
Build Simple CLI / build (push) Failing after 1s
Some checks failed
Build Simple CLI / build (push) Failing after 1s
- Add community release and integration documentation - Add production deployment and testing framework guides - Add live-build configuration with hooks and package lists - Add VM management and testing scripts - Update .gitignore to block build artifacts and large files - Remove old bootc package file - Add comprehensive project completion summary
This commit is contained in:
joe
parent
9e9d4ea8d2
commit
d0d29139e5
52 changed files with 2994 additions and 162 deletions
267
README.md
267
README.md
|
|
@ -1,182 +1,149 @@
|
|||
# Simple CLI - Particle-OS Development System
|
||||
# Particle-OS Simple-CLI
|
||||
|
||||
Simple CLI is a Debian-based Particle-OS system focused on providing a clean, CLI-oriented development environment with container-based development tools.
|
||||
## 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
|
||||
|
||||
- **Base System**: Debian Trixie with OSTree
|
||||
- **Container Runtime**: Podman with full container support
|
||||
- **Development Tools**: Both Toolbox and Distrobox for development environments
|
||||
- **Build System**: Just-based automation with comprehensive recipes
|
||||
- **Immutable Design**: Atomic updates with rollback capability
|
||||
- ✅ **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
|
||||
|
||||
## Development Environments
|
||||
## Quick Start
|
||||
|
||||
Simple CLI provides two powerful development environment tools:
|
||||
### Build the Container
|
||||
|
||||
### 1. Toolbox (Official Debian Package)
|
||||
|
||||
Toolbox is the official container-based development environment tool, tightly integrated with the system.
|
||||
|
||||
#### Quick Start
|
||||
```bash
|
||||
# Create a development environment
|
||||
toolbox create dev
|
||||
|
||||
# Enter the development environment
|
||||
toolbox enter dev
|
||||
|
||||
# Install development tools
|
||||
apt update
|
||||
apt install gcc make git python3-pip
|
||||
|
||||
# Work on projects without affecting the immutable host
|
||||
just build-with-tools-ssh
|
||||
```
|
||||
|
||||
#### Features
|
||||
- **Native Debian integration** - Uses Debian Trixie containers
|
||||
- **Host filesystem access** - Full access to your home directory
|
||||
- **Package management** - Use APT to install any tools
|
||||
- **System integration** - Access to host network, USB devices, display
|
||||
|
||||
### 2. Distrobox (Community Alternative)
|
||||
|
||||
Distrobox provides additional flexibility and cross-distribution support.
|
||||
|
||||
#### Quick Start
|
||||
```bash
|
||||
# Create a development environment
|
||||
distrobox create dev --image debian:trixie
|
||||
|
||||
# Enter the development environment
|
||||
distrobox enter dev
|
||||
|
||||
# Install development tools
|
||||
apt update
|
||||
apt install build-essential git python3-pip
|
||||
|
||||
# Work on projects with full flexibility
|
||||
```
|
||||
|
||||
#### Features
|
||||
- **Cross-distribution support** - Can use Ubuntu, Fedora, or other images
|
||||
- **Advanced container management** - More flexible than Toolbox
|
||||
- **Multiple backends** - Supports both Docker and Podman
|
||||
- **Custom configurations** - Highly configurable for specific needs
|
||||
|
||||
## Using Just Commands
|
||||
|
||||
Simple CLI includes comprehensive Just-based automation:
|
||||
### Test the Integration
|
||||
|
||||
```bash
|
||||
# Setup development environment
|
||||
just setup-dev
|
||||
|
||||
# Create development environments
|
||||
just create-dev-toolbox # Create Toolbox environment
|
||||
just create-dev-distrobox # Create Distrobox environment
|
||||
|
||||
# Enter environments
|
||||
just dev-toolbox # Enter Toolbox environment
|
||||
just dev-distrobox # Enter Distrobox environment
|
||||
|
||||
# Test functionality
|
||||
just test-toolbox # Test Toolbox
|
||||
just test-distrobox # Test Distrobox
|
||||
|
||||
# List all environments
|
||||
just list-envs # Show all development environments
|
||||
|
||||
# Clean up
|
||||
just cleanup-envs # Remove all development environments
|
||||
```
|
||||
|
||||
## When to Use Which Tool?
|
||||
|
||||
### Use Toolbox When:
|
||||
- **Native Debian development** - Working with Debian-specific tools
|
||||
- **System integration** - Need tight integration with host system
|
||||
- **Official support** - Prefer officially supported tools
|
||||
- **Simple workflows** - Basic development environment needs
|
||||
|
||||
### Use Distrobox When:
|
||||
- **Cross-distribution** - Need tools from other distributions
|
||||
- **Custom configurations** - Require specific container setups
|
||||
- **Advanced workflows** - Complex development environment needs
|
||||
- **Flexibility** - Want more control over container configuration
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Toolbox Configuration
|
||||
- **`/etc/containers/toolbox.conf`** - Main Toolbox configuration
|
||||
- **`/etc/profile.d/toolbox.sh`** - Shell integration and welcome messages
|
||||
- **`/usr/lib/tmpfiles.d/toolbox.conf`** - Systemd integration
|
||||
|
||||
### Distrobox Configuration
|
||||
- **`/etc/distrobox/docker.ini`** - Docker backend configuration
|
||||
- **`/etc/distrobox/podman.ini`** - Podman backend configuration
|
||||
|
||||
## Building and Testing
|
||||
|
||||
```bash
|
||||
# Build the container image
|
||||
just build
|
||||
|
||||
# Test the image
|
||||
just test
|
||||
|
||||
# Generate bootable image
|
||||
just generate-bootable
|
||||
|
||||
# Full pipeline
|
||||
just pipeline
|
||||
```
|
||||
|
||||
## System Requirements
|
||||
### Run the Demo
|
||||
|
||||
- **Container Runtime**: Podman or Docker
|
||||
- **Storage**: 10GB+ for development environments
|
||||
- **Memory**: 4GB+ RAM recommended
|
||||
- **Architecture**: x86_64 (amd64)
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
podman run --rm simple-cli:latest /usr/local/bin/verify-tools
|
||||
```
|
||||
|
||||
### Concept Demonstration
|
||||
|
||||
```bash
|
||||
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. **Permission Denied**: Ensure your user is in the appropriate groups
|
||||
```bash
|
||||
sudo usermod -a -G podman $USER
|
||||
newgrp podman
|
||||
```
|
||||
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
|
||||
|
||||
2. **Container Creation Fails**: Check container runtime status
|
||||
```bash
|
||||
podman system info
|
||||
systemctl status podman.socket
|
||||
```
|
||||
### Debug Commands
|
||||
|
||||
3. **Network Issues**: Verify host networking
|
||||
```bash
|
||||
ip addr show
|
||||
toolbox enter dev -- ip addr show
|
||||
```
|
||||
```bash
|
||||
# Check tool availability
|
||||
podman run --rm simple-cli:latest which bootc
|
||||
|
||||
### Getting Help
|
||||
# Verify OSTree status
|
||||
podman run --rm simple-cli:latest ostree --version
|
||||
|
||||
- **Toolbox**: [containertoolbx.org](https://containertoolbox.org/)
|
||||
- **Distrobox**: [github.com/89luca89/distrobox](https://github.com/89luca89/distrobox)
|
||||
- **Particle-OS**: Project documentation and community
|
||||
# Test package management
|
||||
podman run --rm simple-cli:latest apt-ostree list | head -10
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Simple CLI is part of the Particle-OS project. Contributions are welcome!
|
||||
This project demonstrates the core Particle-OS concepts. To contribute:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Test with `just test`
|
||||
5. Submit a pull request
|
||||
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
|
||||
|
||||
This project is part of Particle-OS and follows the same licensing terms.
|
||||
Part of the Particle-OS project - Debian-based immutable operating system.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue