92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
# 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`).
|