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)

```bash
# 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:
   ```bash
   source ~/op_zesticai_non_prod.sh
   ```

2. Inject secrets and deploy:
   ```bash
   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:
```bash
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
```bash
ssh bigbox
docker compose ps
docker logs gitea
```

### Check S3 connectivity
```bash
ssh bigbox
docker exec gitea curl -s http://s3storage:8333/
```

### Reset PostgreSQL password
```bash
ssh bigbox
docker compose exec db psql -U gitea -c "ALTER USER gitea WITH PASSWORD 'newpassword';"
```

### View S3 buckets
```bash
ssh bigbox
curl -s http://localhost:8888/bucket/
```

## Backup

To back up the Gitea data:

```bash
# 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`:
   ```yaml
   image: gitea/gitea:NEW_VERSION
   ```

2. Re-inject secrets and deploy:
   ```bash
   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