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

# Install dependencies
sudo apt update
sudo apt install -y \
  ostree \
  podman \
  jq \
  curl \
  wget

From Source

Shell Script Version (Current)

# 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)

# 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 for details.

Quick Start

Basic Layer Creation

# 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

# Create layer using container isolation (Apx-style)
./apt-layer.sh --container particleos/base/trixie particleos/gaming/trixie steam wine

OCI Export

# Export layer as OCI image
./apt-layer.sh --oci-export particleos/gaming/trixie particleos/gaming:latest

Usage

Layer Creation

apt-layer <base-branch> <new-branch> [packages...]

Examples:

# 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

apt-layer --container <base-branch> <new-branch> [packages...]

Examples:

# 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

apt-layer --oci-export <branch> <image-name>

Examples:

# 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

# 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

# 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

# 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:

# 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:

# 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

# Build layer from recipe
apt-layer --recipe gaming.recipe

# Build multiple layers from recipes
apt-layer --recipe-dir ./recipes

Advanced Usage

Custom Scripts

# 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

# Exclude specific packages
apt-layer particleos/base/trixie particleos/minimal/trixie essential-package \
  --exclude "unwanted-package1" --exclude "unwanted-package2"

Layer Dependencies

# Specify layer dependencies
apt-layer particleos/base/trixie particleos/desktop/trixie kde-plasma-desktop \
  --depends "particleos/gaming/trixie"

Integration with ParticleOS

Build System Integration

# Use apt-layer in ParticleOS build system
./scripts/build-images/apt-layer.sh particleos/base/trixie particleos/gaming/trixie steam wine

CI/CD Integration

# 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

   # Check repository path
   ls -la $OSTREE_REPO
   
   # Initialize repository if needed
   ostree init --repo=$OSTREE_REPO --mode=archive-z2
   

2. Container runtime not available

   # Install podman
   sudo apt install podman
   
   # Or use Docker
   export CONTAINER_RUNTIME="docker"
   

3. Package installation fails

   # Check package availability
   apt-cache search package-name
   
   # Update package lists
   sudo apt update
   

Debug Mode

# Enable debug logging
export LOG_LEVEL="debug"
./apt-layer.sh particleos/base/trixie particleos/test/trixie test-package

Development

Building from Source

# 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

# 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 file for details.

Acknowledgments

• Inspired by rpm-ostree
• Container approach inspired by Vanilla OS Apx
• Built for ParticleOS

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Wiki: GitHub Wiki