Initial commit

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

README.md

@@ -0,0 +1,91 @@
+# Gitea Homelab Automation (`git.bhatfamily.in`)
+Automated Docker-based setup for a self-hosted Gitea server with PostgreSQL, persistent storage at `/media/rbhat/DATA/gitea`, and lifecycle scripts for install, test, and uninstall.
+## What this repository provides
+- `docker-compose.yml` for:
+  - `gitea/gitea:1.24.2`
+  - `postgres:16-alpine`
+  - optional TLS reverse proxy (`caddy:2.10-alpine`, profile: `tls`)
+- Idempotent lifecycle scripts:
+  - `scripts/install.sh`
+  - `scripts/test.sh`
+  - `scripts/uninstall.sh`
+- Environment template: `.env.example`
+- Troubleshooting and network/DNS notes in `docs/`
+## Layout
+- Host storage root: `/media/rbhat/DATA/gitea`
+- Gitea data volume: `/media/rbhat/DATA/gitea/gitea-data`
+- Repository root (host): `/media/rbhat/DATA/gitea/gitea-data/git/repositories`
+- PostgreSQL data: `/media/rbhat/DATA/gitea/postgres`
+- Caddy data/config: `/media/rbhat/DATA/gitea/caddy-data`, `/media/rbhat/DATA/gitea/caddy-config`
+## Prerequisites
+- Docker + Docker Compose plugin installed
+- `curl` installed
+- `ufw` optional (if active, scripts add/remove rules for Gitea ports)
+- Sudo access to manage firewall rules
+## Quick start (baseline, no TLS profile)
+1. Copy and edit environment values:
+   - `cp .env.example .env`
+   - Change at least:
+     - `POSTGRES_PASSWORD`
+     - `GITEA_SECRET_KEY`
+     - `GITEA_INTERNAL_TOKEN`
+2. Install/start stack:
+   - `./scripts/install.sh`
+3. Validate setup:
+   - `./scripts/test.sh`
+4. Open Gitea UI:
+   - `http://localhost:3000` (or your configured HTTP port)
+## Quick start (TLS reverse proxy profile)
+1. Ensure `.env` has correct values:
+   - `GITEA_DOMAIN=git.bhatfamily.in`
+   - `GITEA_ROOT_URL=https://git.bhatfamily.in/`
+   - `TLS_EMAIL=<your-email>` (used by Caddy for ACME account contact)
+2. Ensure DNS + router/NAT are configured first (see `docs/cloudflare-networking.md`).
+3. Install with TLS profile:
+   - `./scripts/install.sh --with-tls --open-public-web`
+4. Test TLS profile (strict):
+   - `./scripts/test.sh --with-tls`
+5. If DNS/cert is still propagating, run non-blocking external check:
+   - `./scripts/test.sh --with-tls --allow-pending-external`
+6. Access:
+   - `https://git.bhatfamily.in`
+## Uninstall
+- Stop and remove containers, keep data:
+  - `./scripts/uninstall.sh`
+- Stop and remove containers including TLS profile:
+  - `./scripts/uninstall.sh --with-tls`
+- Remove added 80/443 firewall rules too (if added with install flag):
+  - `./scripts/uninstall.sh --with-tls --close-public-web`
+- Stop and remove containers and delete persistent data:
+  - `./scripts/uninstall.sh --with-tls --purge-data`
+- Non-interactive full teardown:
+  - `./scripts/uninstall.sh --with-tls --purge-data --purge-images --close-public-web --yes`
+## Port defaults
+- Host HTTP: `3000` -> container `3000`
+- Host SSH: `2222` -> container `22`
+- TLS profile ports: `80`, `443` -> Caddy
+## Firewall behavior
+When UFW is active:
+- install always adds:
+  - `allow <GITEA_HTTP_PORT>/tcp` (comment: `Gitea HTTP`)
+  - `allow <GITEA_SSH_PORT>/tcp` (comment: `Gitea SSH`)
+- install with `--open-public-web` also adds:
+  - `allow 80/tcp` (comment: `Gitea TLS HTTP-01`)
+  - `allow 443/tcp` (comment: `Gitea TLS HTTPS`)
+- uninstall always removes Gitea HTTP/SSH rules
+- uninstall with `--close-public-web` removes 80/443 rules
+## Cloudflare and home network changes
+See `docs/cloudflare-networking.md` for complete instructions.
+## Troubleshooting
+See `docs/troubleshooting.md` for diagnostics and common fixes.
+## Backup basics
+- Backup application data:
+  - `/media/rbhat/DATA/gitea/gitea-data`
+- Backup PostgreSQL data:
+  - `/media/rbhat/DATA/gitea/postgres`
+- If TLS profile used, backup Caddy state too:
+  - `/media/rbhat/DATA/gitea/caddy-data`
+  - `/media/rbhat/DATA/gitea/caddy-config`
+For consistent backups, stop containers first:
+- `docker compose --env-file .env -f docker-compose.yml down`
+Then archive directories and restart with `./scripts/install.sh` (or with `--with-tls`).