atomic-apt is a wrapper for apt, and integration to initramfs-tools that manages atomic system installations using btrfs.

goal

Having a writable / file system often ends up with you installing arbitrary packages into it and making other arbitrary modifications that you forget about later, you accumulate technical debt.

You also replace files non-atomically, causing potential issues at runtime.

atomic ensures that all operations are commited knowingly, by having any changes to your root file system discarded at boot, and requiring explicit upgrades and changes in a snapshot that needs a reboot to be activated.

technical details

In atomic, the / partition contains 4 subvolumes/snapshots:

@ is a writable snapshot that contains the currently booted OS
@oldboot is a read-only snapshot of the previous boot
@latest is a read-only image
@next is a writable snapshot of @next while upgrading

In early boot, before mounting /, atomic's initramfs-tools hooks:

snapshot @ to read-only @oldboot
snapshot @latest to writable @

When performing atomic upgrade, atomic shell, etc, we:

take writable snapshot of @latest as @next
bind-mount /sys /proc /dev into @next
perform the requested operation in @next
swap @next and @latest
delete the old @latest (or keep a timestamped snapshot)

commands

The atomic(8) command is a wrapper that performs the snapshot magic and provides the following subcommands:

atomic shell:

Open a shell in a writable snapshot and commit afterwards
atomic commit [<snapshot>]:

Commit the currently booted system or the given snapshot as the latest snapshot.
atomic upgrade, atomic full-upgrade, atomic install, atomic remove, atomic satisfy:

Perform the requested command as apt <apt command> inside the writable snapshot, after performing an apt update

rationale

This approach allows you to continue to install packages into your normal writable system, but they'll disappear after a reboot. This means you can freely run apt build-dep and hack around without having to worry about cleaning that up ever again.

The commit model also allows you an alternative model where you commit a known-good system for persistence.

TBD:

snapshot history

We should be able to maintain previous boot and image snapshots, be able to list them, delete them, autoclean them

For autoclean, we employ a retention policy with numbers of count, hourly, daily, weekly, yearly snapshots; similar to borg(1). The count limit counts individual commits, by setting it you can e.g. always keep the 5 latest commits.

apt-btrfs-snapshot migration

Existing apt-btrfs-snapshot users should be migrated to atomic(8) with an equivalent autocommit policy, and an equivalent autoclean retention policy (or we can pick a new default).

julian-klode/atomic-apt.md