apt-ostree/.notes/packaging_deb

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

#!/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

#!/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

#!/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

<!-- /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

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

# 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

# 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

# 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

# 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