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 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.yourdomain.com 22

Container Won't Start / Crashes on Boot

Check the logs first:

docker logs 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 -it gitblixt 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.