Initial commit

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

docs/cloudflare-networking.md

@@ -0,0 +1,52 @@
+# Cloudflare DNS + Home Network Setup for `git.bhatfamily.in`
+## Goal
+Expose local Gitea securely from home network while preserving Git-over-SSH support.
+## Recommended Cloudflare DNS records
+Create DNS records in Cloudflare for zone `bhatfamily.in`:
+1. `A` record
+   - Name: `git`
+   - Content: your home public IPv4
+   - Proxy status: **DNS only** (gray cloud)
+2. Optional `AAAA` record
+   - Name: `git`
+   - Content: your home public IPv6
+   - Proxy status: **DNS only**
+## Why DNS-only is recommended
+This setup uses direct inbound routing for both HTTPS and custom SSH (`2222` by default). DNS-only avoids Cloudflare proxy protocol limitations around direct SSH forwarding.
+## Router/NAT rules
+Create forwards to this server's LAN IP:
+- TCP 80 -> `<server_lan_ip>:80` (ACME challenge + redirect)
+- TCP 443 -> `<server_lan_ip>:443` (HTTPS via Caddy)
+- TCP 2222 -> `<server_lan_ip>:2222` (Git SSH)
+## Firewall alignment
+If UFW is active, use install flag to open public web ports:
+- `./scripts/install.sh --with-tls --open-public-web`
+To close those later:
+- `./scripts/uninstall.sh --with-tls --close-public-web`
+## ISP constraints check
+Some ISPs block inbound ports. Validate from outside your network:
+- `curl -I https://git.bhatfamily.in`
+- `nc -vz git.bhatfamily.in 2222`
+If blocked, use alternate routing (VPN/tunnel) or ISP-compatible ports.
+## Recommended hardening
+- Keep strong secrets in `.env`
+- Restrict SSH source ranges if practical
+- Keep containers patched (`docker compose pull` and recreate)
+- Add off-host backups for gitea/postgres/caddy data directories
+
+## Post-cutover verification checklist
+Run these after DNS/NAT/firewall updates to confirm end-to-end readiness:
+1. DNS resolution
+   - `dig +short git.bhatfamily.in A`
+2. HTTPS response and redirect chain
+   - `curl -I https://git.bhatfamily.in`
+   - `curl -I http://git.bhatfamily.in`
+3. Certificate validity/issuer
+   - `openssl s_client -connect git.bhatfamily.in:443 -servername git.bhatfamily.in </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates`
+4. Git SSH port reachability
+   - `nc -vz git.bhatfamily.in 2222`
+5. Stack self-check
+   - `./scripts/test.sh --with-tls`
+If any check fails during first-time propagation, run:
+- `./scripts/test.sh --with-tls --allow-pending-external`
+Then re-run strict checks once DNS/certificate propagation completes.

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