# 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