apt-layer/README.md

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