Release layout and updates

Ironforge is a rolling system. Each release is a matching pair of read-only SquashFS images: one mounted at /usr and one mounted at /opt. The pair must always come from the same release.

Release IDs

Release IDs are UTC timestamps in YYYYMMDDHHMM form. For example, 202607111230 identifies the release created at 12:30 UTC on 11 July 2026.

Published releases are discovered through signed repository metadata rather than by listing files in object storage:

forge repo list

Use --json when another program needs the release list:

forge repo list --json

Files on an installed system

All local SquashFS images are stored beneath /var/ironforge/images:

/var/ironforge/images/
├── current -> releases/202607111230
└── releases/
    └── 202607111230/
        ├── manifest.json
        ├── usr.sqfs
        └── opt.sqfs

The images/current link selects both members of the release at once. The initrd defaults to /var/ironforge/images/current/usr.sqfs and /var/ironforge/images/current/opt.sqfs, and resolves the selected directory once before mounting the pair. No image links are needed at / or the /var/ironforge top level.

Forge supports alternate installation roots for staging and tests; forge repo pull --dest DIR stores images under DIR/images/. The live boot and dinit integration use /var/ironforge/images.

Download and activate a release

Download, verify, and select the latest release:

forge repo pull

Select a specific release to roll back or reproduce an older system:

forge repo pull 202607111230

To download and verify a release without selecting it:

forge repo pull 202607111230 --no-activate

Forge verifies the signed repository metadata, the release manifest, file sizes, SHA-256 hashes, and SquashFS structure before changing images/current. A failed or interrupted download leaves the currently selected release unchanged.

Selecting a release does not immediately remount the running system. A normal reboot applies both /usr and /opt. forge soft-reboot refreshes both images without restarting the kernel.

Retention and disk usage

Downloaded release directories are retained to make rollback possible. Forge does not automatically delete old releases, so periodically inspect /var/ironforge/images/releases and available disk space. Never remove the directory named by images/current, or a release still mounted at /usr or /opt. Use forge repo list --local to see selected and running releases.

Moving an existing installation

Move the former /var/ironforge/releases/ directory into images/releases/ and replace its current link with images/current -> releases/<ID> for the same selected ID. Move older loose images and their checksum files into images/legacy/, then remove the old top-level image aliases. Rename files on the same filesystem so running loop mounts keep their backing inodes.

Install the updated initrd and shutdown hook and update any explicit sqfs=/optsqfs= kernel arguments before rebooting. Those arguments override the new defaults. The new layout does not create compatibility aliases at the old locations. Historical rollback images remain available in the image store.