gitea-infrastructure/HANDOVER.md

Gitea Infrastructure Handover Document

Overview

Self-hosted Gitea instance running on bigbox server with S3 storage, PostgreSQL, and Prometheus monitoring.

URL: https://git.terraphim.cloud GitHub Mirror: https://github.com/terraphim/gitea-infrastructure

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Internet                              │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS (port 443)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Caddy Reverse Proxy                      │
│                  (terraphim.cloud, existing)                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ git.terraphim.cloud -> localhost:3000
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Docker Network (gitea)                   │
├─────────────────────────────────────────────────────────────┤
│  Gitea (port 3000)  │  PostgreSQL  │  SeaweedFS (S3)        │
│  - Attachments      │  (port 5432) │  - S3 (port 8333)      │
│  - Avatars          │              │  - Filer (port 8888)    │
│  - LFS              │              │  - Volume (port 8080)     │
│                     │              │  - Master (port 9333)   │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Tailscale Network                         │
│           Prometheus (100.106.66.7:9000) - internal         │
│           S3 (100.106.66.7:8333) - internal only             │
└─────────────────────────────────────────────────────────────┘

Services

Service	Port	Access	Description
Gitea	3000	localhost (via Caddy)	Git web UI
Gitea SSH	22/222	Public	Git over SSH
PostgreSQL	5432	Docker internal	Database
SeaweedFS S3	8333	Tailscale only	S3-compatible storage
SeaweedFS Filer	8888	Docker internal	File interface
Prometheus	9000	Tailscale only	Metrics

Server Access

Server: bigbox (100.106.66.7)

# SSH to bigbox
ssh bigbox

# Navigate to stack directory
cd ~/gitea-stack

# View container status
docker compose ps

# View logs
docker compose logs -f gitea

# Restart Gitea
docker compose restart server

# Stop entire stack
docker compose down

# Start stack
docker compose up -d

1Password Secrets

Vault: TerraphimPlatform

Item	Purpose
gitea-postgres	PostgreSQL password
gitea-s3	S3 access key and secret key

Re-deploying with 1Password

1. Source the 1Password authentication:

   source ~/op_zesticai_non_prod.sh
   

2. Inject secrets and deploy:

   cd ~/gitea-stack
   op inject --in-file ../gitea_config/docker-compose.yml.template --out-file docker-compose.yml
   docker compose up -d
   

Storage Configuration

S3 Buckets

• gitea - Attachments, avatars, repository files
• gitea-lfs - Git LFS objects

Gitea Storage Settings

The following storage types are configured to use S3 (Minio):

• [attachment] - File attachments
• [picture] - Avatars and images
• [lfs] - Git LFS objects
• [storage] - Default storage configuration

Local storage is used for:

• Git repositories (/data/git/repositories)
• Database (PostgreSQL)

Caddy Configuration

Caddy is already running on bigbox. The git route is appended to /etc/caddy/Caddyfile:

git.terraphim.cloud {
    reverse_proxy localhost:3000
}

To update Caddy config:

ssh bigbox
sudo vim /etc/caddy/Caddyfile
sudo caddy reload

Monitoring

Prometheus: http://100.106.66.7:9000 (Tailscale only)

Scrape targets configured in prometheus/prometheus.yml.

Troubleshooting

Check Gitea status

ssh bigbox
docker compose ps
docker logs gitea

Check S3 connectivity

ssh bigbox
docker exec gitea curl -s http://s3storage:8333/

Reset PostgreSQL password

ssh bigbox
docker compose exec db psql -U gitea -c "ALTER USER gitea WITH PASSWORD 'newpassword';"

View S3 buckets

ssh bigbox
curl -s http://localhost:8888/bucket/

Backup

To back up the Gitea data:

# On bigbox
cd ~/gitea-stack
docker compose stop
tar -czf gitea-backup-$(date +%Y%m%d).tar.gz gitea/ postgres/ seaweedfs/
docker compose start

Updates

To update Gitea to a new version:

1. Edit docker-compose.yml.template:

   image: gitea/gitea:NEW_VERSION
   

2. Re-inject secrets and deploy:

   source ~/op_zesticai_non_prod.sh
   op inject --in-file ../gitea_config/docker-compose.yml.template --out-file docker-compose.yml
   docker compose up -d --build
   

GitHub Mirroring

See MIRRORING-GUIDE.md for bidirectional GitHub ↔ Gitea mirroring setup.

Key Files

File	Description
docker-compose.yml.template	Template with 1Password references
Caddyfile	Caddy reverse proxy config
deploy-to-bigbox.sh	Deployment script
s3_config.json.template	SeaweedFS S3 config template
prometheus/prometheus.yml	Prometheus scrape config
.github/workflows/*.yml	GitHub Actions for mirroring

Contacts

• Infrastructure owner: Alex
• 1Password vault: TerraphimPlatform