Initial commit - realms platform

devops/forgejo-server/README.md

@@ -0,0 +1,137 @@
+# Forgejo Server Setup
+
+Git server with CI/CD for realms.india infrastructure.
+
+## Prerequisites
+
+- Droplet with Docker and Docker Compose installed (via Terraform cloud-init)
+- Volume mounted at `/mnt/forgejo`
+- DNS A record pointing to droplet IP
+
+## Initial Setup
+
+### 1. Copy configuration files
+
+```bash
+# SSH to Forgejo server via jump host
+ssh realms-forgejo
+
+# Copy files to /opt/forgejo
+cd /opt/forgejo
+# (upload docker-compose.yml, Caddyfile, .env.example)
+```
+
+### 2. Generate secrets and configure environment
+
+```bash
+cd /opt/forgejo
+cp .env.example .env
+
+# Generate secure values
+echo "FORGEJO_SECRET_KEY=$(openssl rand -hex 32)"
+echo "FORGEJO_INTERNAL_TOKEN=$(openssl rand -hex 32)"
+echo "FORGEJO_JWT_SECRET=$(openssl rand -hex 32)"
+echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)"
+
+# Edit .env with generated values
+vim .env
+```
+
+### 3. Start Forgejo (without runner)
+
+```bash
+docker compose up -d forgejo-db forgejo caddy
+docker compose logs -f forgejo
+```
+
+### 4. Initial Forgejo Configuration
+
+1. Visit `https://bit.realms.pub`
+2. Create admin account (first user becomes admin)
+3. Configure settings as needed
+
+### 5. Register the Actions Runner
+
+```bash
+# Get runner token from Forgejo
+# Site Administration > Actions > Runners > Create new Runner
+
+# Register the runner
+docker compose run --rm forgejo-runner \
+  forgejo-runner register \
+  --instance https://bit.realms.pub \
+  --token YOUR_RUNNER_TOKEN \
+  --name realms-runner \
+  --labels ubuntu-latest,docker \
+  --no-interactive
+
+# Start the runner
+docker compose up -d forgejo-runner
+```
+
+### 6. Verify Setup
+
+```bash
+# Check all services
+docker compose ps
+
+# Check logs
+docker compose logs -f
+
+# Test Git SSH
+ssh -T git@bit.realms.pub -p 2222
+```
+
+## Maintenance
+
+### View logs
+```bash
+docker compose logs -f [service]
+```
+
+### Restart services
+```bash
+docker compose restart [service]
+```
+
+### Backup
+```bash
+# Stop services
+docker compose down
+
+# Backup volumes
+tar -czvf forgejo-backup-$(date +%Y%m%d).tar.gz /mnt/forgejo
+
+# Restart
+docker compose up -d
+```
+
+### Update Forgejo
+
+```bash
+# Pull new image
+docker compose pull forgejo
+
+# Recreate container
+docker compose up -d forgejo
+```
+
+## Troubleshooting
+
+### Runner won't start
+- Ensure runner is registered first
+- Check `/mnt/forgejo/runner-data/.runner` exists
+- Check logs: `docker compose logs forgejo-runner`
+
+### SSL certificate issues
+- Ensure DNS is properly configured
+- Check Caddy logs: `docker compose logs caddy`
+- Caddy auto-obtains certs, may take a minute on first start
+
+### Database connection issues
+- Check PostgreSQL is healthy: `docker compose ps`
+- Check logs: `docker compose logs forgejo-db`
+
+### Git SSH not working
+- Verify port 2222 is open in firewall
+- Test: `ssh -T git@bit.realms.pub -p 2222 -v`