61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# 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
|