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

The live installation and release state are stored under /var/ironforge:

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

The usr.sqfs and opt.sqfs links are stable boot paths. The releases/current link selects both members of the active release at once, so the system cannot intentionally select /usr from one generation and /opt from another.

Although Forge supports alternate roots for staging and tests, the boot and dinit integration currently expect the live installation at /var/ironforge.

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 releases/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 /usr without restarting the kernel, but it does not remount /opt; use a normal reboot when a release changes /opt.

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/releases and available disk space. Never remove the directory named by releases/current.