Linux DX: define Debian/Ubuntu COW options on ext4

[JanJakes]

Context

ForkPress needs cheap copy-on-write branch directories while preserving ordinary local paths that PHP, Git, editors, WP-CLI, backup tools, and shells can use directly.

On Debian/Ubuntu, the common default filesystem is still ext4. That matters because mainstream ext4 does not provide the ordinary-file reflink/COW primitive ForkPress needs for cheap materialized branch copies.

Refs #6.

Summary

For Debian/Ubuntu, ForkPress should be probe-based:

1. Try native Linux FICLONE in the actual project directory.
2. Use materialized COW branches when the current filesystem supports reflinks, for example Btrfs or XFS with reflink enabled.
3. On ext4, do not pretend cheap COW is available. ForkPress must either guide the user to COW-capable storage, use a mount-based adapter, or fall back to explicit full copy.
4. Treat full copy as a degraded mode, not the normal COW path.

The key tradeoff is the same as on Windows/NTFS: on ext4 we cannot have all three at once:

• cheap COW branches;
• ordinary writable local paths;
• zero extra OS/storage setup.

One of those has to give.

Filesystem Options

Existing Btrfs/XFS Storage

This is the best Linux path.

If the current project directory supports FICLONE, ForkPress can keep the current materialized branch model:

• every branch is an ordinary directory tree;
• unchanged file contents share storage through filesystem reflinks;
• writes to one branch do not mutate the source branch;
• no daemon or mounted provider process is needed beyond the normal filesystem.

Likely supported filesystems:

• Btrfs;
• XFS with reflink support enabled.

ForkPress should not assume by distro or filesystem name alone. It should create a probe file, clone it with FICLONE, mutate the destination, then verify the source is unchanged.

Default ext4 Storage

On ext4, FICLONE should be expected to fail. ForkPress cannot create cheap block-sharing branch copies in place.

Recommended behavior:

• forkpress doctor storage should explain that the current path is on storage without reflink support.
• forkpress init should either fail closed for COW mode or make full-copy mode very explicit.
• The message should point users to a guided setup command, not leave them guessing.

Possible message shape:

This directory does not support filesystem copy-on-write clones.
On Debian/Ubuntu ext4, ForkPress cannot create cheap COW branches in place.
Run `forkpress setup linux-cow-volume` to create a Btrfs/XFS-backed ForkPress volume,
or rerun with an explicit full-copy option if you accept slower, larger branches.

Proposed Guided Setup

Add a command such as:

forkpress setup linux-cow-volume

Possible responsibilities:

• detect distro and current storage capabilities;
• check for needed tools:

command -v mkfs.btrfs btrfs mkfs.xfs xfs_info

• if missing, print an install command:

sudo apt-get update
sudo apt-get install -y btrfs-progs xfsprogs

• create a sparse image file under a stable ForkPress location;
• format it as Btrfs or XFS with reflink support;
• mount it at a user-facing path such as ~/ForkPressCow;
• arrange remounting through a clear systemd/fstab/udisks path;
• set ownership/permissions for the current user;
• initialize or offer to initialize the first site there;
• verify FICLONE works before declaring success.

This setup will generally need sudo for loop devices, formatting, and persistent mounts. That should be explicit.

Btrfs vs XFS

Both are reasonable COW volume targets.

Btrfs advantages:

• native COW filesystem;
• reflinks are a core feature;
• good conceptual fit for cheap branch copies.

XFS advantages:

• mature and widely deployed;
• reflink is available on modern XFS filesystems;
• good performance profile.

Implementation should probably support either, but pick one default for the guided flow. If we pick XFS, verify reflink support after formatting with xfs_info and the same actual FICLONE probe. If we pick Btrfs, still verify with the actual probe instead of trusting assumptions.

Tool Availability

Ubuntu 24.04.4 desktop and live-server manifests include both packages:

• btrfs-progs
• xfsprogs

Debian packages are available in the archive, but ForkPress should not assume they are installed on a normal ext4 Debian system.

For existing reflink-capable storage, ForkPress does not need these userland tools. It only needs the kernel/filesystem to support FICLONE.

For creating a guided COW volume, ForkPress does need filesystem administration tools such as:

• mkfs.btrfs / btrfs from btrfs-progs;
• mkfs.xfs / xfs_info from xfsprogs.

We should not vendor these binaries into the ForkPress release. They are filesystem administration tools and should come from the distro.

FUSE / OverlayFS Considerations

FUSE can work, but it changes the product shape.

Costs:

• requires /dev/fuse and fusermount/distro configuration;
• depends on a running user-space filesystem process;
• paths can hang or fail if the provider process dies;
• correctness depends on implementing filesystem semantics well enough for PHP, Git, editors, SQLite, file locks, renames, symlinks, permissions, and watchers;
• allow_other and non-privileged mount behavior depend on local configuration.

Kernel OverlayFS or fuse-overlayfs may be useful as advanced Linux backends, especially on ext4, but they are not equivalent to filesystem reflinks:

• branch views become mounted overlay views;
• first write to a lower-layer file copies the whole file into the upper layer;
• mount lifecycle has to be managed;
• whiteouts/copy-up/rename behavior need careful testing;
• SQLite/database files and large uploads can be expensive on first write.

Docker mostly solves this by owning a daemon/runtime/mount architecture. It stores layers under Docker-managed storage, uses overlay2 in container mount namespaces, and recommends volumes for persistent/write-heavy data. ForkPress's branch tree is itself the product, so we should be more conservative before adopting that model.

Recommended Product Direction

• Primary Linux path: probe FICLONE and use native reflinks on Btrfs/XFS/reflink-capable storage.
• Debian/Ubuntu ext4 path: explain the limitation clearly and offer guided COW volume setup.
• Add forkpress setup linux-cow-volume for users who want cheap branches on ext4 systems.
• Keep FUSE/OverlayFS as possible future advanced adapters, not the first default.
• Keep full-copy materialization as explicit degraded fallback only.

Acceptance Criteria

• forkpress doctor storage reports whether the current directory supports Linux file clones.
• forkpress init on ext4 gives a clear explanation and next step instead of silently using an expensive mode.
• A Linux setup command can create or guide creation of a Btrfs/XFS-backed ForkPress storage location.
• The setup command verifies actual COW behavior with the same probe ForkPress uses for normal initialization.
• Documentation includes Debian/Ubuntu-specific guidance for ext4, Btrfs, XFS, FUSE, OverlayFS, and full-copy tradeoffs.

References

• Linux FICLONE: https://www.man7.org/linux/man-pages/man2/FICLONE.2const.html
• Btrfs reflink docs: https://btrfs.readthedocs.io/en/stable/Reflink.html
• Debian btrfs-progs: https://packages.debian.org/bookworm/btrfs-progs
• Debian xfsprogs: https://packages.debian.org/bookworm/admin/xfsprogs
• Ubuntu 24.04 release manifests: https://releases.ubuntu.com/24.04/
• Docker OverlayFS storage driver docs: https://docs.docker.com/engine/storage/drivers/overlayfs-driver/
• Linux FUSE docs: https://www.kernel.org/doc/html/next/filesystems/fuse.html