vault-dash/docs/DEVOPS_RUNNER_SETUP.md

DevOps Agent Prompt: Forgejo Runner Setup

Context

We have a Python/FastAPI dashboard application called vault-dash that needs CI/CD via Forgejo Actions. The repository is hosted at:

ssh://git@10.100.0.2:2222/bu5hm4nn/vault-dash.git

The project uses:

• Python 3.11/3.12 with FastAPI + NiceGUI
• Docker for containerization
• Forgejo Actions for CI/CD (workflows already exist in .forgejo/workflows/)

Task

Set up a Forgejo runner that can:

1. Execute CI workflows (lint, test, type-check)
2. Build Docker images
3. Deploy to the production VPS over SSH

Infrastructure

Forgejo Server

• URL: http://10.100.0.2:3000 (or appropriate internal URL)
• Git: ssh://git@10.100.0.2:2222

Target Deployment Server (VPS)

• Access: VPN-only
• Requirements: Docker + Docker Compose plugin installed

Steps to Complete

1. Verify Forgejo Actions is Enabled

Check that Actions are enabled in the Forgejo repository:

• Go to repository Settings → Actions
• Ensure "Enable Actions" is checked

2. Create Forgejo Runner Token

On the Forgejo server:

# Option A: Via CLI
forgejo actions generate-runner-token

# Option B: Via API
curl -X POST http://10.100.0.2:3000/api/v1/repos/bu5hm4nn/vault-dash/actions/runners \
  -H "Authorization: token <YOUR_ADMIN_TOKEN>"

Save the generated token for runner registration.

3. Install Forgejo Runner

On the runner host (can be Forgejo server itself or separate machine):

# Download forgejo-runner (adjust version as needed)
VERSION=3.5.1
wget https://code.forgejo.org/forgejo/runner/releases/download/v${VERSION}/forgejo-runner-${VERSION}-linux-amd64
chmod +x forgejo-runner-${VERSION}-linux-amd64
sudo mv forgejo-runner-${VERSION}-linux-amd64 /usr/local/bin/forgejo-runner

# Create runner user
sudo useradd -r -s /bin/false forgejo-runner
sudo mkdir -p /var/lib/forgejo-runner
sudo chown forgejo-runner:forgejo-runner /var/lib/forgejo-runner

4. Register the Runner

# Run as forgejo-runner user
sudo -u forgejo-runner forgejo-runner register \
  --instance-addr http://10.100.0.2:3000 \
  --token <TOKEN_FROM_STEP_2> \
  --runner-name "vault-dash-runner" \
  --labels "docker,linux,ubuntu"

# Create config file at /var/lib/forgejo-runner/.runner

5. Configure for Docker-in-Docker

The CI workflows need to build Docker images. Create/edit the runner config:

# /var/lib/forgejo-runner/config.yaml

runner:
  file: /var/lib/forgejo-runner/.runner
  capacity: 2
  labels:
    - "docker"
    - "linux"
    - "ubuntu"

container:
  network: ""
  options: ""
  valid_volumes:
    - /var/lib/forgejo-runner
    - /var/run/docker.sock
  force_pull: false

Enable Docker socket access:

# Give runner access to Docker
sudo usermod -aG docker forgejo-runner

# Create systemd service
sudo cat > /etc/systemd/system/forgejo-runner.service << 'EOF'
[Unit]
Description=Forgejo Runner
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=forgejo-runner
WorkingDirectory=/var/lib/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner

6. Verify Runner is Connected

# Check runner status
sudo systemctl status forgejo-runner

# Check runner logs
journalctl -u forgejo-runner -f

# Verify in Forgejo UI
# Go to: Repository → Settings → Actions → Runners
# Should show "vault-dash-runner" as online

7. Configure Deployment Secrets

In Forgejo repository, go to Settings → Secrets and variables → Actions and add:

Secret Name	Description	Example Value
DEPLOY_SSH_PRIVATE_KEY	SSH key for VPS access	-----BEGIN OPENSSH PRIVATE KEY-----...
DEPLOY_HOST	VPS IP/hostname	10.100.0.5
DEPLOY_USER	Deploy user on VPS	deploy
NICEGUI_STORAGE_SECRET	Random 32+ char secret	a1b2c3d4e5f6...

8. Create Deploy User on VPS

On the target deployment server:

# Create deploy user
sudo useradd -m -s /bin/bash deploy
sudo usermod -aG docker deploy

# Create deployment directory
sudo mkdir -p /opt/vault-dash
sudo chown deploy:deploy /opt/vault-dash

# Add runner's public key
sudo mkdir -p /home/deploy/.ssh
echo "<RUNNER_SSH_PUBLIC_KEY>" | sudo tee /home/deploy/.ssh/authorized_keys
sudo chmod 700 /home/deploy/.ssh
sudo chmod 600 /home/deploy/.ssh/authorized_keys
sudo chown -R deploy:deploy /home/deploy/.ssh

9. Test the Pipeline

Trigger a test run:

• Push a commit to the main branch, OR
• Go to Actions tab → Select "CI" workflow → "Run workflow"

Verify all jobs pass:

• ✅ lint (ruff + black)
• ✅ test (pytest)
• ✅ type-check (mypy)
• ✅ build (Docker image)
• ✅ security-scan (Trivy)
• ✅ deploy (only on main branch)

Verification Checklist

• Forgejo Actions enabled on repository
• Runner registered and showing as "online"
• Runner has Docker access (can build images)
• Secrets configured in repository settings
• Deploy user created on VPS with Docker access
• SSH key authentication works from runner to VPS
• CI workflow passes on test commit
• Deploy workflow can reach VPS and run docker commands

Troubleshooting

Runner can't connect to Forgejo

• Check network connectivity: curl http://10.100.0.2:3000
• Verify token hasn't expired (tokens are single-use)

Docker build fails

• Ensure runner user is in docker group
• Check Docker socket permissions: ls -la /var/run/docker.sock
• Restart Docker daemon: sudo systemctl restart docker

Deploy job fails to SSH

• Test SSH manually: ssh -i <key> deploy@<VPS_IP>
• Check key permissions: chmod 600 ~/.ssh/id_ed25519
• Verify host is in known_hosts or StrictHostKeyChecking no

Health check fails after deploy

• Check container logs: docker logs vault-dash
• Verify port 8000 is accessible: curl http://127.0.0.1:8000/health
• Check Docker network connectivity

Files Referenced

• .forgejo/workflows/ci.yaml - Lint, test, type-check
• .forgejo/workflows/deploy.yaml - Build, scan, deploy
• scripts/deploy.sh - Deployment script
• Dockerfile - Container build
• docker-compose.deploy.yml - Production compose file

Success Criteria

After completion:

1. Pushing to main triggers CI pipeline automatically
2. All CI checks pass (lint, test, type-check)
3. Docker image builds and pushes to registry
4. Image deploys to VPS via SSH
5. Application accessible at http://<VPS_IP>:8000/health

---

Please complete these steps and report:

1. Runner registration result (token created, runner online)
2. Secrets configured (list of secret names, not values)
3. Test pipeline run URL and result
4. Any issues encountered during setup