A Galleon backup consists of three parts — all three are mandatory:
- The PostgreSQL database — the artifact catalog of all formats (including container image metadata), users and permissions, settings.
- The storage directory (
storage.default.local.rootas a whole:blobs/,docker/, and thegalleon-storage.jsonmarker) — the artifact content. - The encryption key file (
security.secret_key_file) — without it a database dump is not restorable: the external registry credentials and service secrets cannot be decrypted (see Secrets and the encryption key).
A backup of the database alone is useless: without the storage directory there are no artifacts, without the key file — no access to the encrypted settings.
Backup order
The consistency rule: the database must never be ahead of the storage.
Extra files in the storage without database records only take up space; database records without files in the storage mean lost artifacts: every download of such an artifact fails.
Therefore a backup is taken in this order: the database first, the storage directory second. Everything published between the two moments lands in the copy as extra files.
A concurrently running garbage collection can break this rule: if someone deletes an artifact between the database dump and the storage copy, the garbage collection may also delete the file that the already-taken dump references.
Deleted content stays on disk for at least gc.grace_period
(a day by default), so a backup that fits into that period
is consistent on its own.
If the backup window is longer than the grace period, or the period has been reduced, pause the garbage collection for the duration of the work with the “Pause” button on the “Settings” → “Garbage Collection” page (Storage and garbage collection). The same can be done with an API request when the backup is driven by a script. The pause stops both the scheduled cycles and the manual run. It lasts a limited time, a day by default, and lifts itself automatically, so a forgotten pause will not stop reclaiming space forever. The “Resume” button lifts it as soon as the backup is complete.
Both copies can also be taken as atomic snapshots of the same moment (LVM, ZFS, cloud snapshots), pausing writes.
Restore
The restore order:
- Restore the key file — the same one that was in effect at the backup moment.
- Restore the database.
- Restore the storage directory — from a copy taken at the same time as the database dump or later. A storage copy taken earlier than the dump leaves records with no files behind, and those artifacts stop downloading.
- Restart all servers of the instance.
Restore the storage directory together with the galleon-storage.json marker:
without it the server does not start.
Restore the database as a whole: selectively restoring individual tables desynchronizes the service secrets, the artifact catalog, and the image metadata. Extra storage files that got into the copy remain on disk: the garbage collection does not delete them. They must not be deleted manually (Storage and garbage collection).