Add DevOps agent prompt for Forgejo runner setup
Comprehensive setup guide including: - Forgejo Actions configuration - Runner installation and registration - Docker-in-Docker setup - Deployment secrets configuration - VPS deploy user creation - Verification checklist
This commit is contained in:
Bu5hm4nn
256
docs/DEVOPS_RUNNER_SETUP.md
Normal file
256
docs/DEVOPS_RUNNER_SETUP.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# /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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user