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:

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