beeta/devops/forgejo-server/README.md

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

# 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

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)

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

# 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

# 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

docker compose logs -f [service]

Restart services

docker compose restart [service]

Backup

# 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

# 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