# apt-ostree Debian Package Packaging Guide

## Overview

This document outlines the packaging strategy and dependencies for creating a .deb package for apt-ostree distribution on Debian/Ubuntu systems.

NONE OF THIS IS PUT INTO PLACE YET
THIS IS JUST PRE EMPTIVE NOTE TAKING

## Core Dependencies

### Required Dependencies
```bash
# Essential system dependencies
Depends: 
  ostree (>= 2024.5),
  libostree-1-1 (>= 2024.5),
  systemd (>= 247),
  libsystemd0 (>= 247),
  libc6 (>= 2.34),
  libgcc-s1 (>= 3.0),
  libstdc++6 (>= 12)

# APT/DPKG integration
Depends:
  apt (>= 2.4),
  dpkg (>= 1.21),
  libapt-pkg6.0 (>= 2.4),
  libdpkg-perl (>= 1.21)

# D-Bus communication
Depends:
  dbus (>= 1.12),
  libdbus-1-3 (>= 1.12)

# Security and sandboxing
Depends:
  bubblewrap (>= 0.7),
  libseccomp2 (>= 2.5)
```

### Recommended Dependencies
```bash
# Enhanced functionality
Recommends:
  bubblewrap (>= 0.7),          # Script sandboxing
  systemd-container (>= 247),    # Container support
  flatpak (>= 1.14),            # Application containerization
  snapd (>= 2.58),              # Alternative containerization
  distrobox (>= 1.4),           # Development containers
  toolbox (>= 0.0.20)           # Fedora-style containers
```

### Optional Dependencies
```bash
# Development and debugging
Suggests:
  ostree-tests (>= 2024.5),     # OSTree testing utilities
  apt-ostree-doc,               # Documentation package
  apt-ostree-dev,               # Development headers
  cargo (>= 1.70),              # Rust development
  rustc (>= 1.70)               # Rust compiler
```

## Package Structure

### Binary Package: `apt-ostree`
```bash
# Main executable
/usr/bin/apt-ostree              # Main CLI binary
/usr/bin/apt-ostreed             # Daemon binary

# Systemd service
/lib/systemd/system/apt-ostreed.service
/etc/dbus-1/system.d/org.aptostree.dev.conf

# Configuration
/etc/apt-ostree/
/etc/apt-ostree/config.toml
/etc/apt-ostree/repositories.d/

# Documentation
/usr/share/doc/apt-ostree/
/usr/share/man/man1/apt-ostree.1.gz
/usr/share/man/man8/apt-ostreed.8.gz

# Examples and templates
/usr/share/apt-ostree/
/usr/share/apt-ostree/examples/
/usr/share/apt-ostree/templates/
```

### Development Package: `apt-ostree-dev`
```bash
# Development headers
/usr/include/apt-ostree/
/usr/lib/x86_64-linux-gnu/libapt_ostree.a
/usr/lib/x86_64-linux-gnu/libapt_ostree.so
/usr/lib/x86_64-linux-gnu/pkgconfig/apt-ostree.pc

# Rust crate
/usr/lib/rustlib/x86_64-unknown-linux-gnu/lib/libapt_ostree.rlib
```

### Documentation Package: `apt-ostree-doc`
```bash
# Comprehensive documentation
/usr/share/doc/apt-ostree-doc/
/usr/share/doc/apt-ostree-doc/html/
/usr/share/doc/apt-ostree-doc/examples/
/usr/share/doc/apt-ostree-doc/tutorials/
```

## Build Dependencies

### For Building the Package
```bash
# Essential build tools
Build-Depends:
  debhelper (>= 13),
  dh-cargo (>= 25),
  cargo (>= 1.70),
  rustc (>= 1.70),
  pkg-config (>= 0.29),
  cmake (>= 3.16)

# OSTree development
Build-Depends:
  libostree-dev (>= 2024.5),
  libostree-1-1 (>= 2024.5),
  ostree (>= 2024.5)

# APT development
Build-Depends:
  libapt-pkg-dev (>= 2.4),
  apt (>= 2.4),
  dpkg-dev (>= 1.21)

# Systemd development
Build-Depends:
  libsystemd-dev (>= 247),
  systemd (>= 247)

# D-Bus development
Build-Depends:
  libdbus-1-dev (>= 1.12),
  dbus (>= 1.12)

# Security development
Build-Depends:
  libseccomp-dev (>= 2.5),
  bubblewrap (>= 0.7)

# Documentation
Build-Depends:
  doxygen (>= 1.9),
  graphviz (>= 2.44),
  pandoc (>= 2.17)
```

## Package Configuration

### debian/control
```bash
Source: apt-ostree
Section: admin
Priority: optional
Maintainer: Your Name <your.email@example.com>
Build-Depends: [see Build Dependencies above]

Package: apt-ostree
Architecture: any
Depends: [see Required Dependencies above]
Recommends: [see Recommended Dependencies above]
Suggests: [see Optional Dependencies above]
Description: Immutable Debian/Ubuntu system management
 apt-ostree provides atomic, immutable system management for Debian/Ubuntu
 systems, similar to rpm-ostree for Fedora/RHEL. It enables atomic updates,
 rollbacks, and client-side package layering while maintaining system
 integrity and reliability.
 .
 Features:
  * Atomic system updates with instant rollback
  * Client-side package layering
  * OSTree-based content-addressed storage
  * D-Bus daemon for privileged operations
  * Bubblewrap sandboxing for security
  * Full compatibility with rpm-ostree CLI

Package: apt-ostree-dev
Architecture: any
Depends: apt-ostree (= ${binary:Version})
Description: Development files for apt-ostree
 This package contains development headers and libraries for building
 applications that integrate with apt-ostree.

Package: apt-ostree-doc
Architecture: all
Depends: apt-ostree (= ${binary:Version})
Description: Documentation for apt-ostree
 This package contains comprehensive documentation, examples, and tutorials
 for apt-ostree.
```

### debian/rules
```bash
#!/usr/bin/make -f

%:
	dh $@

override_dh_auto_build:
	# Build Rust project
	cargo build --release
	# Build documentation
	doxygen Doxyfile
	# Build man pages
	pandoc docs/apt-ostree.1.md -s -t man -o debian/apt-ostree.1
	pandoc docs/apt-ostreed.8.md -s -t man -o debian/apt-ostreed.8

override_dh_auto_install:
	# Install binaries
	install -D target/release/apt-ostree debian/apt-ostree/usr/bin/apt-ostree
	install -D target/release/apt-ostreed debian/apt-ostree/usr/bin/apt-ostreed
	# Install systemd service
	install -D src/daemon/apt-ostreed.service debian/apt-ostree/lib/systemd/system/
	# Install D-Bus policy
	install -D src/daemon/org.aptostree.dev.conf debian/apt-ostree/etc/dbus-1/system.d/
	# Install configuration
	install -d debian/apt-ostree/etc/apt-ostree/
	install -D config/config.toml debian/apt-ostree/etc/apt-ostree/
	# Install documentation
	install -D docs/*.md debian/apt-ostree-doc/usr/share/doc/apt-ostree-doc/
	install -D docs/html/* debian/apt-ostree-doc/usr/share/doc/apt-ostree-doc/html/
	# Install man pages
	install -D debian/apt-ostree.1 debian/apt-ostree/usr/share/man/man1/
	install -D debian/apt-ostreed.8 debian/apt-ostree/usr/share/man/man8/
```

## Post-Installation Scripts

### debian/apt-ostree.postinst
```bash
#!/bin/sh
set -e

# Reload systemd
systemctl daemon-reload

# Enable daemon service
systemctl enable apt-ostreed.service

# Reload D-Bus
systemctl reload dbus

# Create default configuration if it doesn't exist
if [ ! -f /etc/apt-ostree/config.toml ]; then
    install -m 644 /usr/share/apt-ostree/config.toml.default /etc/apt-ostree/config.toml
fi

# Set up log directory
install -d -m 755 /var/log/apt-ostree

echo "apt-ostree has been installed successfully."
echo "The daemon service has been enabled and will start on boot."
echo "Configuration is available at /etc/apt-ostree/config.toml"
```

### debian/apt-ostree.prerm
```bash
#!/bin/sh
set -e

# Stop daemon service
systemctl stop apt-ostreed.service || true

# Disable daemon service
systemctl disable apt-ostreed.service || true
```

## Security Considerations

### D-Bus Policy
```xml
<!-- /etc/dbus-1/system.d/org.aptostree.dev.conf -->
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <policy user="root">
    <allow own="org.aptostree.dev"/>
    <allow send_destination="org.aptostree.dev"/>
    <allow receive_sender="org.aptostree.dev"/>
  </policy>
  <policy context="default">
    <allow send_destination="org.aptostree.dev"/>
    <allow receive_sender="org.aptostree.dev"/>
  </policy>
</busconfig>
```

### Systemd Service Security
```ini
# /lib/systemd/system/apt-ostreed.service
[Unit]
Description=apt-ostree Daemon
Documentation=man:apt-ostreed(8)
After=network.target

[Service]
Type=dbus
BusName=org.aptostree.dev
ExecStart=/usr/bin/apt-ostreed
Restart=on-failure
RestartSec=5
User=root
Group=root
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/apt-ostree /var/log/apt-ostree /etc/apt-ostree
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictRealtime=true
RestrictSUIDSGID=true
LockPersonality=true
MemoryDenyWriteExecute=true

[Install]
WantedBy=multi-user.target
```

## Distribution Strategy

### Target Distributions
- **Ubuntu**: 22.04 LTS (Jammy), 24.04 LTS (Noble), 24.10 (Mantic)
- **Debian**: 12 (Bookworm), 13 (Trixie)
- **Derivatives**: Linux Mint, Pop!_OS, Elementary OS

### Repository Structure
```bash
# PPA structure (for Ubuntu)
apt-ostree/
├── jammy/          # Ubuntu 22.04 LTS
├── noble/          # Ubuntu 24.04 LTS
├── mantic/         # Ubuntu 24.10
└── devel/          # Development releases

# Debian repository structure
apt-ostree/
├── bookworm/       # Debian 12
├── trixie/         # Debian 13
└── sid/            # Unstable
```

### Build Infrastructure
```bash
# GitHub Actions workflow for automated builds
.github/workflows/build-packages.yml

# Launchpad PPA for Ubuntu packages
# Debian repository for Debian packages
# OBS (Open Build Service) for multiple distributions
```

## Testing Strategy

### Package Testing
```bash
# Install in clean environment
pbuilder-dist jammy build apt-ostree_*.dsc

# Test installation
dpkg -i apt-ostree_*.deb

# Test functionality
apt-ostree status
apt-ostree daemon-ping

# Test uninstallation
dpkg -r apt-ostree
```

### Integration Testing
```bash
# Test with real OSTree environment
# Test with different Ubuntu/Debian versions
# Test with various system configurations
# Test upgrade scenarios
```

## Future Considerations

### Version Compatibility
- **OSTree version requirements**: Minimum 2024.5, recommend latest
- **Systemd version requirements**: Minimum 247, recommend latest
- **APT version requirements**: Minimum 2.4, recommend latest

### Distribution Integration
- **Ubuntu integration**: Work with Ubuntu team for official inclusion
- **Debian integration**: Submit to Debian for official packaging
- **Derivative support**: Ensure compatibility with major derivatives

### Long-term Maintenance
- **Security updates**: Regular security patches and updates
- **Feature updates**: New features and improvements
- **Bug fixes**: Bug reports and fixes
- **Documentation**: Keep documentation current and comprehensive