GitBlixt
Docs Navigation

Troubleshooting

SSL Certificate Not Issuing

Symptoms: Browser shows a certificate warning or "connection refused" on HTTPS.

Checklist:

  • Is port 80 open in your firewall/security group? Let's Encrypt requires it for the ACME challenge.
  • Does GITBLIXT_HOST match the domain pointing at your server? The cert is issued for that exact hostname.
  • Check container logs: docker compose logs gitblixt | grep -i ssl
  • Let's Encrypt has rate limits (5 failed attempts per hour per domain). If you've hit them, wait an hour before retrying.

Workaround: Set SSL_MODE=manual and supply your own certificate while you resolve the issue.

SSH Not Working

Symptoms: git clone or ssh -T fails or times out.

Checklist:

  • Is port 22 (or your custom GITBLIXT_SSH_PORT) open in your firewall?
  • Is another process already using port 22 on the host? Check with ss -tlnp | grep :22.
  • Have you added your SSH public key to your GitBlixt account? See SSH Keys.
  • Test connectivity: nc -zv #git.vianet.us 22

Container Won't Start / Crashes on Boot

Check the logs first (the app is a Swarm service, so use docker service logs):

docker service logs --tail 100 gitblixt

Common causes:

  • GITBLIXT_SECRET_KEY_BASE not set or too short — must be 64+ characters
  • Port already in use — another process has port 80, 443, or 22. Find it with ss -tlnp
  • Volume permission issue — ensure the Docker volume is writable
  • External database unreachable — if using DATABASE_URL, verify the connection string and that the DB is accessible from the container

Forgot Admin Password

If email is configured, use the "Forgot password" link on the login page.

If email is not configured, reset via the container:

    docker exec $(docker ps -q -f name=gitblixt.1) bin/gitblixt eval \
  "Gitblixt.Accounts.reset_password_admin(\"[email protected]\", \"new-password\")"

Registration is Closed / Can't Create Account

An administrator may have disabled public registration. Contact your GitBlixt administrator, or if you are the administrator, re-enable it by setting GITBLIXT_REGISTRATION_ENABLED=true and restarting.

Install / CI: "permission denied … /var/run/docker.sock"

Cause: the host Docker daemon runs with userns-remap or in rootless mode. GitBlixt drives the host Docker through the mounted socket, but a remapped container "root" (host uid 100000) can't open the root:docker socket. The same cause makes /data files owned by 100000/100070.

Check:

    docker info | grep -iE 'userns|rootless'   # any output = remapped/rootless
cat /etc/docker/daemon.json                  # look for "userns-remap"

Fix (run as a rootful daemon with no remap — what GitBlixt expects). Disabling remap switches Docker's data-root, so the daemon "forgets" swarm/services/images — your /data bind mount is safe; you re-init swarm and recreate the service after. 

    cd /opt/gitblixt
docker service scale gitblixt=0 ; docker compose -p gitblixt down
sudo sed -i '/"userns-remap"/d' /etc/docker/daemon.json
sudo chown -R 0:0 /opt/gitblixt/data
sudo chown -R 70:70 /opt/gitblixt/data/postgres    # alpine postgres uid
sudo systemctl restart docker
docker info | grep -iE 'userns|rootless'           # should print nothing now
docker swarm init --advertise-addr 127.0.0.1
docker compose -p gitblixt up -d
# then recreate the gitblixt service (re-run the installer)

"docker swarm init … --live-restore … is incompatible with swarm mode"

Swarm mode can't run with live-restore enabled. Set "live-restore": false in /etc/docker/daemon.json (or remove the line), sudo systemctl restart docker, then re-run docker swarm init --advertise-addr 127.0.0.1.

Install: "This node is not a swarm manager"

The compose networks are overlay networks, which require Swarm. Initialize it: docker swarm init --advertise-addr 127.0.0.1. (The installer does this automatically; if it was skipped, the daemon likely had live-restore on — see above.)

Restore: private key error / "pem_entry_decode"

Your backup private key is in OpenSSH format (-----BEGIN OPENSSH PRIVATE KEY-----); GitBlixt needs PEM/PKCS#1 (-----BEGIN RSA PRIVATE KEY-----). Convert it: 

    chmod 600 backup-private.pem
ssh-keygen -p -m PEM -N "" -f backup-private.pem

Restore: pg_restore "unrecognized configuration parameter transaction_timeout"

The backup was produced by a Postgres client newer than the target server (the transaction_timeout GUC is PG17+, rejected by PG16). Current images pin the client to match the bundled Postgres, so new backups are clean. The error is also ignored by pg_restore ("errors ignored on restore: 1") — the data still restores; restore into an empty DB and run bin/migrate as in Backup & Restore.

Database auth fails ("28P01 … password authentication failed") after reinstall

Postgres only honors POSTGRES_PASSWORD when it initializes a fresh data directory. If you re-ran the installer (which regenerates the password in .env) against an existing Postgres volume, they no longer match. Either restore the old password to .env, or — if the DB has no data yet — wipe and re-init: docker compose -p gitblixt rm -sf postgres && sudo rm -rf /opt/gitblixt/data/postgres && docker compose -p gitblixt up -d postgres.

SSH: "REMOTE HOST IDENTIFICATION HAS CHANGED" after a migration

Expected — host keys aren't in the backup, so a restored server generates new ones. It is not an attack. Each user clears it with ssh-keygen -R your-host and accepts the new key on the next connection.

Cloudflare error 526 (Invalid SSL certificate)

Cloudflare is in "Full (strict)" mode but your origin doesn't have a valid certificate yet (common right after pointing DNS at a new server). Either let the origin obtain a Let's Encrypt cert — temporarily set the DNS record to "DNS only" (grey cloud) so the ACME challenge reaches it, then re-enable the proxy — or install a Cloudflare Origin Certificate and set SSL_MODE=manual. See SSL & HTTPS.