first commit
This commit is contained in:
commit
06f09b28c1
1 changed files with 390 additions and 0 deletions
390
README.md
Normal file
390
README.md
Normal file
|
|
@ -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 <base-branch> <new-branch> [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 <base-branch> <new-branch> [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 <branch> <image-name>
|
||||
```
|
||||
|
||||
**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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue