Galleon stores data in two tiers:
metadata (the artifact catalog, users, settings) — in PostgreSQL,
artifact content — as files on disk in the storage directory
(storage.default.local.root).
Directory layout
The storage root contains:
blobs/— the content of the package formats. A file is named by the SHA-256 hash of its content, so identical data is stored once, no matter how many repositories and paths reference it.docker/— the manifests and layers of container images, with its own layout. Layers are addressed by checksum as well and are shared between images; they are tracked in separate tables of the same database.galleon-storage.json— the marker that binds the directory to the database. The server creates it on the first start; copy it together with the directory.
On a foreign or unmounted directory the server does not start:
the error message starts with storage identity: and names the cause and the action.
An asset record is stored only in the database and points at a file in the storage. Any number of assets from different repositories may reference the same file, so deleting an asset frees space only when the last reference to the file disappears. The component and asset model is described in Repositories and formats.
A sudden power loss leaves no half-written files that the database already points at.
Garbage collection
The garbage collection does not decide what is outdated: it takes the content nothing references any more. What components to delete is decided by the administrator by hand or by cleanup policies (Cleanup policies).
An artifact deleted from the artifact catalog is not removed from disk immediately: files that are no longer referenced are found and deleted by the background garbage collection. It serves both storage trees in one cycle on one schedule. Uploads do not have to be stopped for the duration of a cycle.
The parameters are the gc configuration block:
| Key | Default | Purpose |
|---|---|---|
auto | true | Scheduled cycles; false disables only the schedule — the manual run always works |
interval | 5m | The pause between scheduled cycles |
grace_period | 24h | The minimum age of deleted content after which its space is reclaimed |
batch_size | 500 | Candidates per scan query |
max_duration | 15m | The ceiling of a single cycle; the remainder is picked up by the next one |
Because of the grace period, space is not reclaimed at once: deleted content stays on disk for at least grace_period. The same value applies to container images.
Observation and manual runs
The “Settings” → “Garbage Collection” page shows the state of the collection: whether a cycle is running right now, when the previous one was (“Last run”), how it ended (“Last result” — a summary such as “OK: N objects reclaimed”), and when the next one is due.
The “Run” button starts a cycle immediately. The run is asynchronous: the interface confirms that the cycle has started while the cycle itself continues in the background — closing the page does not interrupt it. Only one cycle runs at a time; a repeated start is rejected.
Viewing the page requires the nx-tasks-read privilege,
running — nx-tasks-run.
The garbage collection parameters are not changed from the page — only in the server configuration, with a restart.
Pausing for maintenance
The “Pause” button on the same page stops both the scheduled cycles and the manual run. The pause lasts a limited time: a day by default, seven days at most. When the period expires it lifts itself, so a forgotten pause will not stop reclaiming space forever. The “Resume” button lifts it early. The state survives a server restart; if there are several servers, it is shared by all of them.
The pause exists first of all for backups — see Backup for details. It does not affect artifact deletion by users: a component or a repository can be deleted during the pause, the space is reclaimed later.
When the disk is full
A full disk shows up as errors on artifact uploads;
in the server log, such records carry no space left on device in the err field.
Reading keeps working.
To reclaim space, follow these steps:
- Delete the unneeded artifacts in the “Browse” section of the web interface — large and outdated builds first.
- Run the garbage collection with the “Run” button on the “Settings” → “Garbage Collection” page.
- If that frees too little, reduce
grace_periodin the configuration and restart the server: the garbage collection never touches files younger than the grace period.
Do not delete files from the storage directory manually. A file name is the hash of its content, so the name tells nothing about which artifact it belongs to; a file deleted by mistake is not recoverable, is not detected by the garbage collection, and requests for the corresponding artifact start failing.