# 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

## Current edge endpoint map (verified 2026-04-19)
Caddy routes on `443/tcp`:
- `git.bhatfamily.in` -> `gitea:3000`
- `chat.bhatfamily.in` -> `gemma3-chat-ui:8080`
- `openvpn.bhatfamily.in` -> `https://<lan-host>:8445`
- `nxt.bhatfamily.in` -> `https://<lan-host>:8447`
- `vpn.bhatfamily.in` -> `https://<lan-host>:943`

Public TCP ports observed reachable on the shared WAN edge:
- `80`, `443`, `2222`, `3000`, `8000`, `8082`, `8445`, `8447`, `943`

## 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`).