GitBlixt
Docs Navigation

Migrating to a New Server

Moving a GitBlixt instance to a new host is: install GitBlixt on the new server, restore your backup into it, reconcile secrets, then cut over DNS. This page is the end-to-end runbook; the restore mechanics live in Backup & Restore.

Before You Start

  • A recent encrypted backup pair (.tar.gz.enc + .key.enc) and the matching private key in PEM format. Take a fresh backup right before cutover if the old server is still taking traffic — anything created after the backup won't migrate.
  • Know your source server's secret config: does it set APP_SECRETS_KEY, or derive from secret_key_base? Check /opt/gitblixt/.env on the old box.

1. Check the new host's Docker daemon first

GitBlixt drives the host Docker (CI, PaaS deploys, AI jobs) and runs as a Swarm service. Some cloud images ship a Docker config that breaks this. Confirm before installing: 

    docker info | grep -iE 'userns|rootless'   # should print NOTHING
cat /etc/docker/daemon.json                  # must NOT contain "userns-remap"

If userns-remap or rootless mode is on, fix it before going further — see Troubleshooting (it causes permission denied … docker.sock in CI and 100000-owned data files).

2. Install GitBlixt on the New Server

Follow Getting Started. Let it come up empty and healthy (docker service ps gitblixt shows Running) before restoring.

3. Restore Your Data

Run the full restore from Backup & Restore (stage files → empty the DB → restore → migrate), then do the encryption-key continuity step so your encrypted columns decrypt.

4. Re-deploy Your PaaS Apps

Restoring the DB, repos, and uploads does not recreate the Docker containers for apps you deployed via the built-in PaaS — those lived only on the old host. Re-trigger each app's deploy (push, or re-run its pipeline) so the deploy worker rebuilds the image and re-registers its Caddy route on the new host.

5. Cut Over DNS

  • Point your domain (and any deployed-app domains) at the new server's IP.
  • If you front GitBlixt with Cloudflare, see the SSL & HTTPS page — a fresh origin without a valid cert yet shows Cloudflare error 526 under "Full (strict)". Let the origin obtain a Let's Encrypt cert (temporarily grey-cloud the record) or use a Cloudflare Origin Certificate, then re-enable the proxy.
  • Make sure the SSH port (default 22) is open. Users will get a one-time "host key changed" warning because host keys aren't in the backup — they clear it with ssh-keygen -R your-host.

6. Verify, Then Decommission the Old Server

  • Log in; open a private repo's settings and an encrypted field (AI key / app env var) — confirms key continuity.
  • Clone over HTTPS and SSH; push to a repo.
  • Confirm scheduled backups are armed (Admin → Backups) and that a backup can write (data dir ownership is correct).
  • Only then retire the old server.