feat: Gitea deployment with 1Password and Caddy

Complete infrastructure deployment including: - Docker Compose templates with 1Password integration (op://) - Caddy reverse proxy configuration for git.terraphim.cloud - Automated deployment script (deploy-to-bigbox.sh) - Comprehensive documentation and deployment article - Network isolation: Public (Gitea) + Tailscale (Prometheus/S3) - Security: No hardcoded secrets, all via 1Password Services deployed: - Gitea 1.22.6 (Git hosting) - PostgreSQL 15 (Database) - SeaweedFS (S3-compatible storage) - Prometheus (Monitoring) Excludes: - docker-compose.yml (contains resolved secrets) - s3_config.json (contains resolved secrets) - Data directories (gitea/, postgres/, seaweedfs/) Refs: Private deployment on bigbox with TerraphimPlatform vault
2026-07-16 00:00:32 +02:00 · 2026-02-16 19:40:19 +00:00
parent 850d8b7680
commit 4a4a0351aa
13 changed files with 2620 additions and 200 deletions
@@ -0,0 +1,323 @@
+# 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:
+
+```bash
+# 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)
+```bash
+# 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
+```bash
+# 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:
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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:
+```bash
+# 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
+```bash
+# 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:
+   ```bash
+   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
+```bash
+# 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
+```bash
+# 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.