From 06f09b28c144216cce2b135c3f98df115802930f Mon Sep 17 00:00:00 2001 From: robojerk Date: Thu, 3 Jul 2025 08:29:32 -0700 Subject: [PATCH] first commit --- README.md | 390 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fa24c10 --- /dev/null +++ b/README.md @@ -0,0 +1,390 @@ +# apt-layer + +A modern tool for creating OSTree layers using apt packages, inspired by rpm-ostree and Vanilla OS Apx. Designed for Ubuntu/Debian-based immutable systems like ParticleOS. + +## Overview + +`apt-layer` is a tool that allows you to add, inspect, and rollback layers on OSTree-based systems using apt packages. It can be used by system builders and end users, similar to `rpm-ostree` for Fedora Silverblue/Bazzite, but designed specifically for Ubuntu/Debian systems. + +## Features + +- ✅ **Layer Creation** - Add new layers to existing OSTree images +- ✅ **Container Isolation** - Apx-style container-based layer creation +- ✅ **OCI Export** - Export OSTree branches as OCI images +- ✅ **Layer Management** - List, inspect, and rollback layers +- ✅ **Recipe Support** - Declarative layer definitions +- ✅ **Dependency Resolution** - Automatic package dependency handling +- ✅ **Conflict Detection** - Detect and resolve layer conflicts +- ✅ **Production Ready** - Enterprise-grade error handling and logging + +## Installation + +### Prerequisites + +```bash +# Install dependencies +sudo apt update +sudo apt install -y \ + ostree \ + podman \ + jq \ + curl \ + wget +``` + +### From Source + +#### Shell Script Version (Current) +```bash +# Clone the repository +git clone https://github.com/your-org/apt-layer.git +cd apt-layer + +# Make executable +chmod +x apt-layer.sh + +# Install (optional) +sudo cp apt-layer.sh /usr/local/bin/apt-layer +``` + +#### C Implementation (Development) +```bash +# Clone the repository +git clone https://github.com/your-org/apt-layer.git +cd apt-layer + +# Build C implementation +make + +# Install (optional) +sudo make install +``` + +**Note**: The C implementation is currently in development and provides the same functionality as the shell script version. See [README-C.md](README-C.md) for details. + +## Quick Start + +### Basic Layer Creation + +```bash +# Create a gaming layer on top of base +./apt-layer.sh particleos/base/trixie particleos/gaming/trixie steam wine + +# Create a desktop layer on top of gaming +./apt-layer.sh particleos/gaming/trixie particleos/desktop/trixie kde-plasma-desktop +``` + +### Container-Based Layer Creation + +```bash +# Create layer using container isolation (Apx-style) +./apt-layer.sh --container particleos/base/trixie particleos/gaming/trixie steam wine +``` + +### OCI Export + +```bash +# Export layer as OCI image +./apt-layer.sh --oci-export particleos/gaming/trixie particleos/gaming:latest +``` + +## Usage + +### Layer Creation + +```bash +apt-layer [packages...] +``` + +**Examples:** +```bash +# Gaming layer +apt-layer particleos/base/trixie particleos/gaming/trixie steam wine proton + +# Desktop layer +apt-layer particleos/gaming/trixie particleos/desktop/trixie kde-plasma-desktop sddm + +# User custom layer +apt-layer particleos/desktop/trixie particleos/mycustom/trixie my-favorite-app +``` + +### Container-Based Creation + +```bash +apt-layer --container [packages...] +``` + +**Examples:** +```bash +# Container-based gaming layer +apt-layer --container particleos/base/trixie particleos/gaming/trixie steam wine + +# Container-based development layer +apt-layer --container particleos/base/trixie particleos/dev/trixie build-essential git +``` + +### OCI Export + +```bash +apt-layer --oci-export +``` + +**Examples:** +```bash +# Export as OCI image +apt-layer --oci-export particleos/gaming/trixie particleos/gaming:latest + +# Export with specific tag +apt-layer --oci-export particleos/desktop/trixie particleos/desktop:v1.0 +``` + +### Information Commands + +```bash +# List all available branches +apt-layer --list + +# Show information about a specific branch +apt-layer --info particleos/base/trixie + +# Show help +apt-layer --help +``` + +### Rollback Commands + +```bash +# Rollback to previous commit +apt-layer --rollback particleos/desktop/trixie +``` + +## Layer Architecture + +### Recommended Layer Structure + +``` +particleos/base/trixie # Minimal base system +├── particleos/gaming/trixie # Gaming packages (steam, wine, etc.) +├── particleos/desktop/trixie # Desktop environment (KDE) +├── particleos/dev/trixie # Development tools +└── particleos/custom/trixie # User customizations +``` + +### Layer Types + +1. **Base Layers** - Minimal system with essential packages +2. **Application Layers** - Specific applications (gaming, development, etc.) +3. **Desktop Layers** - Desktop environments (KDE, GNOME, XFCE) +4. **Custom Layers** - User-specific packages and configurations + +## Configuration + +### Environment Variables + +```bash +# OSTree repository path +export OSTREE_REPO="/workspace/cache/ostree-repo" + +# Build directory +export BUILD_DIR="/workspace/cache/build" + +# Container runtime (podman or docker) +export CONTAINER_RUNTIME="podman" +``` + +### Configuration File + +Create `~/.config/apt-layer/config` for persistent settings: + +```bash +# apt-layer configuration +OSTREE_REPO="/workspace/cache/ostree-repo" +BUILD_DIR="/workspace/cache/build" +CONTAINER_RUNTIME="podman" +LOG_LEVEL="info" +``` + +## Recipes + +### Recipe Format + +Create declarative layer definitions in `.recipe` files: + +```yaml +# gaming.recipe +name: "gaming" +base_branch: "particleos/base/trixie" +new_branch: "particleos/gaming/trixie" +packages: + - steam + - wine + - lutris + - proton +custom_scripts: + - "echo 'Gaming layer configured' > /etc/gaming.conf" +files: + - "config/steam.conf:/etc/steam.conf" +``` + +### Using Recipes + +```bash +# Build layer from recipe +apt-layer --recipe gaming.recipe + +# Build multiple layers from recipes +apt-layer --recipe-dir ./recipes +``` + +## Advanced Usage + +### Custom Scripts + +```bash +# Run custom script during layer creation +apt-layer particleos/base/trixie particleos/custom/trixie my-package \ + --script "echo 'Custom configuration' > /etc/custom.conf" +``` + +### Package Exclusions + +```bash +# Exclude specific packages +apt-layer particleos/base/trixie particleos/minimal/trixie essential-package \ + --exclude "unwanted-package1" --exclude "unwanted-package2" +``` + +### Layer Dependencies + +```bash +# Specify layer dependencies +apt-layer particleos/base/trixie particleos/desktop/trixie kde-plasma-desktop \ + --depends "particleos/gaming/trixie" +``` + +## Integration with ParticleOS + +### Build System Integration + +```bash +# Use apt-layer in ParticleOS build system +./scripts/build-images/apt-layer.sh particleos/base/trixie particleos/gaming/trixie steam wine +``` + +### CI/CD Integration + +```yaml +# GitHub Actions example +- name: Create Gaming Layer + run: | + ./apt-layer.sh particleos/base/trixie particleos/gaming/trixie steam wine +``` + +## Troubleshooting + +### Common Issues + +1. **OSTree repository not found** + ```bash + # Check repository path + ls -la $OSTREE_REPO + + # Initialize repository if needed + ostree init --repo=$OSTREE_REPO --mode=archive-z2 + ``` + +2. **Container runtime not available** + ```bash + # Install podman + sudo apt install podman + + # Or use Docker + export CONTAINER_RUNTIME="docker" + ``` + +3. **Package installation fails** + ```bash + # Check package availability + apt-cache search package-name + + # Update package lists + sudo apt update + ``` + +### Debug Mode + +```bash +# Enable debug logging +export LOG_LEVEL="debug" +./apt-layer.sh particleos/base/trixie particleos/test/trixie test-package +``` + +## Development + +### Building from Source + +```bash +# Clone repository +git clone https://github.com/your-org/apt-layer.git +cd apt-layer + +# Make executable +chmod +x apt-layer.sh + +# Run tests +./apt-layer.sh --test +``` + +### Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Add tests +5. Submit a pull request + +### Testing + +```bash +# Run all tests +./apt-layer.sh --test + +# Run specific test +./apt-layer.sh --test --test-name "layer-creation" +``` + +## Roadmap + +### Planned Features + +- [ ] **Graphical Interface** - TUI for layer management +- [ ] **Layer Templates** - Pre-built layer definitions +- [ ] **Remote Repositories** - Support for remote OSTree repos +- [ ] **Layer Signing** - GPG signing for layers +- [ ] **Layer Compression** - Optimize layer storage +- [ ] **Multi-Architecture** - Support for ARM64, etc. +- [ ] **Layer Analytics** - Size and dependency analysis + +### Version History + +- **v1.0.0** - Initial release with basic layer creation +- **v1.1.0** - Added container-based creation +- **v1.2.0** - Added OCI export functionality +- **v1.3.0** - Added recipe support and dependency resolution + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +- Inspired by [rpm-ostree](https://github.com/coreos/rpm-ostree) +- Container approach inspired by [Vanilla OS Apx](https://github.com/Vanilla-OS/apx) +- Built for [ParticleOS](https://github.com/your-org/particleos) + +## Support + +- **Documentation**: [docs/](docs/) +- **Issues**: [GitHub Issues](https://github.com/your-org/apt-layer/issues) +- **Discussions**: [GitHub Discussions](https://github.com/your-org/apt-layer/discussions) +- **Wiki**: [GitHub Wiki](https://github.com/your-org/apt-layer/wiki) \ No newline at end of file