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