Commit `9e4827a050`

9e4827a050e337dd51a558790ecefa1c123b20ea

parent: 5f1152bca4

Verified · cmc

cmc <hello@cleberg.net> · 2026-09-28 22:27 UTC

docs: restore puts the secret key file back before starting gitbayd

Ref #259

Layout: unified · split

.gitbay/wiki/Admin.org +17 −8

 or on a restore host.
 Restore: extract into an empty directory, point =server.root= at it,
-start gitbayd. Host keys are preserved, so clients keep their
+restore =server.secret_key_file= from its own copy (mode 0600, owned
-known_hosts entries; hooks regenerate at startup.
+by the account gitbayd runs as), then start gitbayd. No archive carries
+the key file, and without it gitbayd refuses to start. Host keys are
+preserved, so clients keep their known_hosts entries; hooks regenerate
+at startup.
 ** Schedule and recovery point
 ** Offsite copies
 bay1 also takes a nightly restic snapshot of =/var/lib/gitbay= and
-=/var/lib/gitbay-stage= (the staged database copy) to an S3 bucket at
+=/var/lib/gitbay-stage= (a database copy and =config.toml=, staged
-Scaleway, with a key that can only add snapshots. The key that can
+there) to an S3 bucket at Scaleway, with a key that can only add
+snapshots. Nothing else under =/etc/gitbay= is in it: not the secret
+key file, not =apns.p8=. The key that can
 remove them lives on the operator's machine, in
 =~/.config/gitbay/offsite.env=, and never on bay1: a compromised host
 cannot destroy its own history. Forgetting, pruning and rewriting all
 =server.root=, and therefore in neither the local archives nor the
 main restic repository. It must be copied off the host separately;
 without it a restored database's secrets cannot be opened, and
-gitbayd refuses to start against them.
+gitbayd refuses to start against them. A separate restic repository
+for it and =apns.p8= is planned (runbook D of the data-at-rest plan)
+and not yet in place, so today the only off-host copy is one the
+operator makes by hand after =init= and after every =rotate=.
 #+begin_src sh
 gitbayd admin secrets init     # once; deploy/install.sh does it on first install
 below. The disaster it rehearses is losing bay1, so the local archives
 are gone with it and the sources are the main offsite restic
 repository (repositories, LFS, the staged database, =config.toml=),
-the keys repository (=secret.key=, =apns.p8=), and the operator's
+the off-host copy of =secret.key= and =apns.p8= (a keys repository once
-password manager (=offsite.env=, the keys repository's password and
+runbook D creates it; until then the operator's hand-made copy), and
-token, =backup-identity.txt=). The steps are in the data-at-rest
+the operator's password manager (=offsite.env=, the keys repository's
+password and token once it exists, =backup-identity.txt=). The steps are in the data-at-rest
 plan's operator runbook
 (=docs/plans/2026-09-27-data-at-rest-and-backup.md=).

.gitbay/wiki/Architecture/06-Data-and-Cryptography.org +1 −1

	@@ -45,7 +45,7 @@ throttling (=internal/sshd/sshd.go=).
45	\| API tokens, sessions, login links, email codes, invites \| SHA-256 of a 256-bit random value; the value is shown once and never stored (=internal/store/sessions.go=) \|	45	\| API tokens, sessions, login links, email codes, invites \| SHA-256 of a 256-bit random value; the value is shown once and never stored (=internal/store/sessions.go=) \|
46	\| CI secrets, webhook secrets, mirror tokens, APNs device tokens \| AES-256-GCM under a key file outside the database and outside =server.root=; additional data binds table, column and row (=internal/seal=, =internal/store/secrets.go=) \|	46	\| CI secrets, webhook secrets, mirror tokens, APNs device tokens \| AES-256-GCM under a key file outside the database and outside =server.root=; additional data binds table, column and row (=internal/seal=, =internal/store/secrets.go=) \|
47	\| SQLite file \| mode 0640, directory 0750 \|	47	\| SQLite file \| mode 0640, directory 0750 \|
48	\| Backups \| local archives age-encrypted when =[backup] age_recipients= is set; restic encrypts the offsite copy; neither carries the secret key file, whose offsite copy is a separate keys repository \|	48	\| Backups \| local archives age-encrypted when =[backup] age_recipients= is set; restic encrypts the offsite copy; neither carries the secret key file, which is copied off the host by hand until a separate keys repository is set up \|
49	\| Disk \| no application-level encryption; any disk encryption is the host's \|	49	\| Disk \| no application-level encryption; any disk encryption is the host's \|
50		50
51	The database file or a backup read by anyone other than the =gitbay=	51	The database file or a backup read by anyone other than the =gitbay=

cmd/gitbayd/backup.go +5 −2

 comments that exists nowhere else. Repositories are not in such an archive,
 so it supplements a full backup and does not replace one.
-Restore: extract into an empty directory, point server.root at it, start
+Restore: extract into an empty directory, point server.root at it,
-gitbayd. Host keys are preserved, so clients keep their known_hosts entries.
+restore server.secret_key_file from its own backup (mode 0600, owned by
+the daemon user), start gitbayd. No archive carries the key file, and
+without it gitbayd refuses to start. Host keys are preserved, so clients
+keep their known_hosts entries.
 With [backup] age_recipients set, the archive is encrypted to those age
 public keys and its name ends in .age. --verify then needs --identity

deploy/cloud-init.yaml +6 −1

 #   - opens ufw for 22, 80, 443, 2222
 #
 # It does NOT install the gitbayd binary (it is not hosted anywhere yet);
-# scp it to /usr/local/bin/gitbayd afterward and `systemctl start gitbayd`.
+# scp it to /usr/local/bin/gitbayd afterward, then create the secret key
+# and hand it to the daemon user before starting:
+#   gitbayd --config /etc/gitbay/config.toml admin secrets init
+#   chown gitbay:gitbay /etc/gitbay/secret.key
+#   systemctl start gitbayd
+# On a restore, put the key file's off-host copy there instead of init.
 package_update: true
 packages:

Commit 9e4827a050

Commit `9e4827a050`