gitea-infrastructure/.docs/DEPLOYMENT-SUMMARY.md

Gitea Stack Deployment Summary

Date: 2026-02-16 Target: bigbox (via SSH) Status: Ready for deployment

What Was Done

1. Disciplined Research (Phase 1)

Created comprehensive research document analyzing:

• Current Docker Compose stack (Gitea, PostgreSQL, SeaweedFS, Prometheus)
• Bigbox environment (125GB RAM, 367GB free, Docker 28.1.1, 1Password CLI installed)
• Security requirements (eliminate hardcoded credentials)
• Caddy reverse proxy integration

File: .docs/RESEARCH-gitea-bigbox-deployment.md

2. Disciplined Design (Phase 2)

Created implementation plan with:

• 1Password secrets management using op inject
• Template files with op:// references
• Caddy reverse proxy configuration with automatic HTTPS
• 10-step deployment process
• Complete rollback plan

File: .docs/IMPLEMENTATION-gitea-bigbox-deployment.md

3. Implementation Artifacts Created

Template Files (Safe to Commit)

• docker-compose.yml.template - Docker Compose with 1Password references
• s3_config.json.template - SeaweedFS S3 config with 1Password references
• Caddyfile - Caddy reverse proxy configuration
• .gitignore - Excludes secrets and data directories

Deployment Script

• deploy-to-bigbox.sh - Automated deployment script

Generated Files (NOT in Git - Created at Deploy Time)

• docker-compose.yml - Secrets injected via op inject
• s3_config.json - Secrets injected via op inject

1Password Integration

Prerequisites on Bigbox

1. 1Password CLI installed (/usr/bin/op)
2. Service account script: ~/op_zesticai_non_prod.sh
3. Valid service account token configured

Required Vault Items

Create these in the zesticai-non-prod vault:

# Create gitea-postgres item
op item create \
  --vault="zesticai-non-prod" \
  --category=login \
  --title="gitea-postgres" \
  --generate-password=20,letters,digits \
  username=gitea

# Create gitea-s3 item
op item create \
  --vault="zesticai-non-prod" \
  --category=custom \
  --title="gitea-s3" \
  access-key="$(openssl rand -hex 20)" \
  secret-key="$(openssl rand -hex 40)"

How It Works

1. Template Creation: Files use op://vault/item/field syntax
2. Authentication: Source op_zesticai_non_prod.sh to set OP_SERVICE_ACCOUNT_TOKEN
3. Secret Injection: Run op inject --in-file template --out-file config
4. Deployment: Use injected config files with Docker Compose

Network Architecture

Public Access (via Caddy HTTPS)

Bigbox already runs Caddy with existing services (terraphim.cloud, privacy1st.org). We add Gitea to the existing instance:

Service	Domain	Backend	Access
Gitea	git.terraphim.cloud	localhost:3000	Public HTTPS

Tailscale Network Only (100.106.66.7)

These services are bound to the Tailscale interface and are NOT accessible from the public internet:

Service	Address	Purpose
Prometheus	100.106.66.7:9000	Monitoring
S3 API	100.106.66.7:8333	Object storage
S3 Metrics	100.106.66.7:9327	Prometheus metrics

SSH Access

• Port 222: Git over SSH (exposed on all interfaces)
• Command: git clone ssh://git@bigbox:222/owner/repo.git

Internal Services (Docker Network Only)

• PostgreSQL: Internal Docker network only
• SeaweedFS Master, Volume, Filer: Internal Docker network only

Caddy Configuration

• Existing Instance: Caddy already running on bigbox
• Route Addition: Gitea route added via Caddy Admin API
• SSL: Automatic HTTPS via Let's Encrypt
• Logging: JSON format to /var/log/caddy/gitea-access.log

Deployment Steps

Option 1: Automated (Recommended)

# 1. Create 1Password items first (see above)

# 2. Run deployment script
./deploy-to-bigbox.sh

Option 2: Manual Step-by-Step

See .docs/IMPLEMENTATION-gitea-bigbox-deployment.md for detailed manual steps.

Post-Deployment

Access URLs

After deployment, services will be available at:

Public Access (HTTPS via Caddy):

• Gitea Web: https://git.terraphim.cloud
• Gitea SSH: ssh://bigbox:222

Tailscale Network Only (requires Tailscale connection):

• Prometheus: http://100.106.66.7:9000
• S3 API: http://100.106.66.7:8333
• S3 Metrics: http://100.106.66.7:9327

Local Development (on bigbox):

• Gitea: http://localhost:3000

Important: Prometheus and S3 are intentionally NOT accessible from the public internet. They are bound to the Tailscale interface (100.106.66.7) and require connection to the Tailscale VPN.

Immediate Actions

1. Update DNS: Add entries to your DNS or local /etc/hosts
2. Gitea Setup: Complete initial setup at http://bigbox:3000
3. Change Password: Update default admin password immediately
4. Verify Caddy: Check SSL certificates are generated

Useful Commands

# Check service status
ssh bigbox "cd ~/gitea-stack && docker compose ps"

# View logs
ssh bigbox "cd ~/gitea-stack && docker compose logs -f"

# View Caddy logs
ssh bigbox "sudo tail -f /var/log/caddy/*.log"

# Restart services
ssh bigbox "cd ~/gitea-stack && docker compose restart"

# Reload Caddy config
ssh bigbox "sudo caddy reload --config /etc/caddy/Caddyfile"

Security Improvements

Before (Hardcoded Secrets)

• S3 credentials in s3_config.json
• Database password in docker-compose.yml
• Secrets committed to git

After (1Password Managed)

• All secrets in 1Password vault
• Template files only contain references (op://)
• Secrets injected at deployment time
• Easy secret rotation via 1Password
• .gitignore prevents accidental commits

Caddy Security

• Automatic HTTPS (Let's Encrypt)
• No manual certificate management
• Request logging for audit trail
• Easy to add basic authentication

Rollback

If deployment fails:

# Stop services
ssh bigbox "cd ~/gitea-stack && docker compose down"

# Stop Caddy
ssh bigbox "sudo pkill caddy || sudo systemctl stop caddy"

# Remove deployment
ssh bigbox "rm -rf ~/gitea-stack"

# Remove Caddy config
ssh bigbox "sudo rm /etc/caddy/Caddyfile"

Files Changed/Created

New Files

1. .docs/RESEARCH-gitea-bigbox-deployment.md - Research findings
2. .docs/IMPLEMENTATION-gitea-bigbox-deployment.md - Implementation plan
3. docker-compose.yml.template - Compose template with 1Password refs
4. s3_config.json.template - S3 config template with 1Password refs
5. Caddyfile - Caddy reverse proxy configuration
6. .gitignore - Excludes secrets and data
7. deploy-to-bigbox.sh - Automated deployment script
8. .docs/DEPLOYMENT-SUMMARY.md - This file

Modified Files

• None (original docker-compose.yml and s3_config.json remain unchanged)

Files Excluded from Git

• docker-compose.yml (contains resolved secrets)
• s3_config.json (contains resolved secrets)
• .env (if created)
• gitea/, postgres/, seaweedfs/ (data directories)

Next Steps

1. Create 1Password Items: Run the op item create commands
2. Update Domains: Caddyfile already configured for git.terraphim.cloud
3. Run Deployment: Execute ./deploy-to-bigbox.sh
4. Verify: Check all services are accessible
5. Document: Update this summary with actual domain names and any issues

Troubleshooting

1Password Authentication Fails

# Test on bigbox
ssh bigbox
source ~/op_zesticai_non_prod.sh
op vault list

# If it fails, check service account token is valid

Caddy Route Not Working

# Check if Caddy is running
ssh bigbox "pgrep -x caddy"

# Check existing Caddy routes
ssh bigbox "curl -s http://localhost:2019/config/apps/http/servers/srv0/routes | grep git.terraphim"

# Check Caddy logs
ssh bigbox "sudo tail -f /var/log/caddy/*.log"

# Verify Gitea is responding on localhost:3000
ssh bigbox "curl http://localhost:3000/api/healthz"

Services Not Accessible

# Check container logs
ssh bigbox "cd ~/gitea-stack && docker compose logs"

# Check if containers are running
ssh bigbox "cd ~/gitea-stack && docker compose ps"

# Check Gitea (public via Caddy)
curl https://git.terraphim.cloud/api/healthz

# Check Prometheus/S3 (Tailscale only - must be on Tailscale network)
curl http://100.106.66.7:9000/-/healthy
curl http://100.106.66.7:8333

Cannot Access Prometheus or S3

These services are bound to the Tailscale interface (100.106.66.7) only:

# Verify you're connected to Tailscale
tailscale status

# Verify you can reach the Tailscale IP
ping 100.106.66.7

# Then access services
curl http://100.106.66.7:9000/-/healthy
curl http://100.106.66.7:8333

Secret Injection Fails

# Test op inject manually
ssh bigbox "cd ~/gitea-stack && source ~/op_zesticai_non_prod.sh && op inject --in-file docker-compose.yml.template --dry-run"

Maintenance

Rotating Secrets

1. Update secret in 1Password vault
2. Re-run deployment: ./deploy-to-bigbox.sh
3. Or manually:

   ssh bigbox "cd ~/gitea-stack && source ~/op_zesticai_non_prod.sh && op inject --in-file docker-compose.yml.template --out-file docker-compose.yml && docker compose up -d"
   

Backup

# Backup data directories
rsync -avz bigbox:~/gitea-stack/gitea ./backup/
rsync -avz bigbox:~/gitea-stack/postgres ./backup/
rsync -avz bigbox:~/gitea-stack/seaweedfs ./backup/

Updates

# Update images
ssh bigbox "cd ~/gitea-stack && docker compose pull && docker compose up -d"

# Update Caddy
ssh bigbox "sudo apt update && sudo apt upgrade caddy"

---

Ready to deploy! Run ./deploy-to-bigbox.sh after creating the 1Password vault items.