Initial commit

Co-Authored-By: Oz <oz-agent@warp.dev>

docs/troubleshooting.md

@@ -0,0 +1,60 @@
+# 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