gitea-homelab/docs/troubleshooting.md

Troubleshooting

1) Containers fail to start

• Check compose status:
  • docker compose --env-file .env -f docker-compose.yml ps
• If TLS profile enabled:
  • docker compose --env-file .env -f docker-compose.yml --profile tls ps
• Inspect logs:
  • docker compose --env-file .env -f docker-compose.yml logs gitea
  • docker compose --env-file .env -f docker-compose.yml logs postgres
  • docker compose --env-file .env -f docker-compose.yml --profile tls logs caddy

2) Gitea health endpoint fails

• Local probe:
  • curl -v http://localhost:3000/api/healthz
• If port changed, use your GITEA_HTTP_PORT.
• Confirm mapping:
  • docker compose --env-file .env -f docker-compose.yml ps

3) Database connection errors

• Confirm PostgreSQL health:
  • docker compose --env-file .env -f docker-compose.yml ps postgres
• Re-check .env values:
  • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
• Look for auth failures in postgres logs.

4) Permission issues under /media/rbhat/DATA/gitea

• Ensure current user can read/write this path.
• If needed:
  • sudo chown -R rbhat:rbhat /media/rbhat/DATA/gitea
  • sudo chmod -R u+rwX /media/rbhat/DATA/gitea

5) Firewall blocks access

• Check active rules:
  • sudo ufw status
• Expected allows:
  • <GITEA_HTTP_PORT>/tcp
  • <GITEA_SSH_PORT>/tcp
  • 80/tcp and 443/tcp if TLS profile is internet-exposed

6) TLS cert not issuing

• Ensure git.bhatfamily.in resolves publicly to your home WAN IP.
• Ensure inbound TCP 80 and 443 are forwarded to this host.
• Ensure TLS_EMAIL is set in .env.
• Verify Caddy logs for ACME failures:
  • docker compose --env-file .env -f docker-compose.yml --profile tls logs caddy

7) Port conflicts on 80/443

• Check listeners:
  • ss -tulpen | grep -E '(:80\s|:443\s)'
• Stop conflicting services or disable TLS profile until resolved.

8) DNS resolves but service unreachable

• Verify router forwarding targets correct LAN IP.
• Verify host listening:
  • ss -tulpen | grep -E '3000|2222|80|443'
• Test from external network (mobile hotspot) to avoid NAT loopback confusion.

9) TLS tests fail during propagation

• Strict mode (default) fails until DNS/routing/cert trust is ready:
  • ./scripts/test.sh --with-tls
• Temporary non-blocking mode:
  • ./scripts/test.sh --with-tls --allow-pending-external

10) Reset stack while keeping data

• ./scripts/uninstall.sh --with-tls
• ./scripts/install.sh --with-tls --open-public-web

11) Full clean rebuild

• ./scripts/uninstall.sh --with-tls --purge-data --purge-images --close-public-web --yes
• Re-run install