Add handover document

2026-07-16 00:00:32 +02:00 · 2026-02-16 21:07:43 +00:00
parent e999ed9a4e
commit 2e73ca794f
1 changed files with 220 additions and 0 deletions
@@ -0,0 +1,220 @@
+# 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