9e9d4ea8d2
Some checks failed
Build Simple CLI / build (push) Failing after 1s
- Add apt-ostree, deb-bootupd, and bootc packages to tools/ - Update Containerfile to install Particle-OS tools with dependencies - Add tool verification script and updated welcome message - Update justfile with new build and test recipes - Add comprehensive tool testing and bootable image generation - Successfully integrate 2/3 tools (apt-ostree and bootupd working) - Note: bootc package contains only documentation, not binary Ready for bootable image generation and QEMU testing!
182 lines
5 KiB
Markdown
182 lines
5 KiB
Markdown
# Simple CLI - Particle-OS Development System
|
|
|
|
Simple CLI is a Debian-based Particle-OS system focused on providing a clean, CLI-oriented development environment with container-based development tools.
|
|
|
|
## 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
|
|
|
|
## Development Environments
|
|
|
|
Simple CLI provides two powerful development environment tools:
|
|
|
|
### 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
|
|
```
|
|
|
|
#### 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:
|
|
|
|
```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
|
|
|
|
- **Container Runtime**: Podman or Docker
|
|
- **Storage**: 10GB+ for development environments
|
|
- **Memory**: 4GB+ RAM recommended
|
|
- **Architecture**: x86_64 (amd64)
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Denied**: Ensure your user is in the appropriate groups
|
|
```bash
|
|
sudo usermod -a -G podman $USER
|
|
newgrp podman
|
|
```
|
|
|
|
2. **Container Creation Fails**: Check container runtime status
|
|
```bash
|
|
podman system info
|
|
systemctl status podman.socket
|
|
```
|
|
|
|
3. **Network Issues**: Verify host networking
|
|
```bash
|
|
ip addr show
|
|
toolbox enter dev -- ip addr show
|
|
```
|
|
|
|
### Getting Help
|
|
|
|
- **Toolbox**: [containertoolbx.org](https://containertoolbox.org/)
|
|
- **Distrobox**: [github.com/89luca89/distrobox](https://github.com/89luca89/distrobox)
|
|
- **Particle-OS**: Project documentation and community
|
|
|
|
## Contributing
|
|
|
|
Simple CLI is part of the Particle-OS project. Contributions are welcome!
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test with `just test`
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is part of Particle-OS and follows the same licensing terms.
|