docs: Add Gitea act_runner setup guide for asgard build server
Architecture clarification: - Gitea + SeaweedFS run on PUBLIC docker stack - Act runner runs on ASGARD (Ryzen 9 build server) - Runner connects remotely to git.corrosionmgmt.com New documentation: - ASGARD-RUNNER.md: Complete setup guide for registering and running act_runner as systemd service on asgard - Includes example workflows for companion agent builds - Troubleshooting and security notes Runner capabilities: - Docker access for containerized builds - Native Go/Rust toolchains (already installed) - 16C/32T, 64GB DDR5 for fast builds Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Vantz Stockwell
284
infra/ASGARD-RUNNER.md
Normal file
284
infra/ASGARD-RUNNER.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# Gitea Act Runner Setup (Asgard Build Server)
|
||||
|
||||
**Purpose**: Run CI/CD builds on asgard's powerful hardware (Ryzen 9 7945HX, 64GB DDR5) while Gitea runs on the public docker stack.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Public Stack: Asgard (Build Server):
|
||||
┌──────────────────┐ ┌──────────────────────┐
|
||||
│ Gitea Container │◄───────────│ Act Runner (daemon) │
|
||||
│ git.corrosion... │ registers │ • Docker socket │
|
||||
│ Port: 8090 │ │ • Go/Rust toolchains │
|
||||
└──────────────────┘ │ • 16C/32T, 64GB RAM │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites on Asgard
|
||||
|
||||
1. **Docker installed**
|
||||
```bash
|
||||
docker --version
|
||||
```
|
||||
|
||||
2. **Go installed** (already present per Commander)
|
||||
```bash
|
||||
go version
|
||||
```
|
||||
|
||||
3. **Rust installed** (already present per Commander)
|
||||
```bash
|
||||
rustc --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### Step 1: Download act_runner Binary
|
||||
|
||||
On **asgard**, download the latest act_runner:
|
||||
|
||||
```bash
|
||||
# Create directory for runner
|
||||
mkdir -p ~/gitea-runner
|
||||
cd ~/gitea-runner
|
||||
|
||||
# Download act_runner (check for latest version at gitea.com/gitea/act_runner)
|
||||
wget https://dl.gitea.com/act_runner/0.2.6/act_runner-0.2.6-linux-amd64 -O act_runner
|
||||
chmod +x act_runner
|
||||
```
|
||||
|
||||
### Step 2: Generate Registration Token
|
||||
|
||||
On the **public docker stack** (where Gitea runs):
|
||||
|
||||
1. Navigate to `https://git.corrosionmgmt.com`
|
||||
2. Login as admin
|
||||
3. Go to **Site Administration** → **Actions** → **Runners**
|
||||
4. Click **"Create new Runner"**
|
||||
5. Copy the **registration token** (looks like: `A1B2C3D4E5F6G7H8...`)
|
||||
|
||||
### Step 3: Register Runner on Asgard
|
||||
|
||||
Back on **asgard**, register the runner with your Gitea instance:
|
||||
|
||||
```bash
|
||||
cd ~/gitea-runner
|
||||
|
||||
# Register runner (replace TOKEN with the token from Gitea)
|
||||
./act_runner register \
|
||||
--instance https://git.corrosionmgmt.com \
|
||||
--token YOUR_REGISTRATION_TOKEN_HERE \
|
||||
--name asgard-runner \
|
||||
--labels ubuntu-latest:docker://node:20-bullseye,golang:docker://golang:1.22,rust:docker://rust:latest
|
||||
```
|
||||
|
||||
**Important labels:**
|
||||
- `ubuntu-latest` - Generic Linux builds (Node.js)
|
||||
- `golang` - Go companion agent builds
|
||||
- `rust` - Rust backend builds (if needed)
|
||||
|
||||
This creates a `.runner` config file with credentials.
|
||||
|
||||
### Step 4: Start Runner as Daemon
|
||||
|
||||
Create systemd service for persistent runner:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/gitea-runner.service
|
||||
```
|
||||
|
||||
**Service file contents:**
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Gitea Actions Runner (Asgard)
|
||||
After=docker.service
|
||||
Requires=docker.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=YOUR_USERNAME
|
||||
WorkingDirectory=/home/YOUR_USERNAME/gitea-runner
|
||||
ExecStart=/home/YOUR_USERNAME/gitea-runner/act_runner daemon
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
# Security hardening
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Replace `YOUR_USERNAME`** with your actual username on asgard.
|
||||
|
||||
### Step 5: Enable and Start Service
|
||||
|
||||
```bash
|
||||
# Reload systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Enable runner to start on boot
|
||||
sudo systemctl enable gitea-runner
|
||||
|
||||
# Start the runner
|
||||
sudo systemctl start gitea-runner
|
||||
|
||||
# Check status
|
||||
sudo systemctl status gitea-runner
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
● gitea-runner.service - Gitea Actions Runner (Asgard)
|
||||
Loaded: loaded (/etc/systemd/system/gitea-runner.service; enabled)
|
||||
Active: active (running) since ...
|
||||
```
|
||||
|
||||
### Step 6: Verify Registration
|
||||
|
||||
Back in Gitea web UI:
|
||||
1. Go to **Site Administration** → **Actions** → **Runners**
|
||||
2. You should see **"asgard-runner"** with status: **Online**
|
||||
|
||||
---
|
||||
|
||||
## Testing the Runner
|
||||
|
||||
### Create Test Workflow
|
||||
|
||||
In any Gitea repo, create `.gitea/workflows/test.yml`:
|
||||
|
||||
```yaml
|
||||
name: Test Asgard Runner
|
||||
on: [push]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check runner
|
||||
run: |
|
||||
echo "Running on: $(hostname)"
|
||||
echo "CPU cores: $(nproc)"
|
||||
echo "Memory: $(free -h | grep Mem | awk '{print $2}')"
|
||||
echo "Go version: $(go version)"
|
||||
echo "Rust version: $(rustc --version)"
|
||||
```
|
||||
|
||||
Push to trigger the workflow. Check logs in Gitea Actions tab.
|
||||
|
||||
---
|
||||
|
||||
## Companion Agent Build Workflow (Example)
|
||||
|
||||
Create `.gitea/workflows/build-companion.yml` in the companion-agent repo:
|
||||
|
||||
```yaml
|
||||
name: Build Companion Agent
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: golang
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Build Linux AMD64
|
||||
run: |
|
||||
cd companion-agent
|
||||
GOOS=linux GOARCH=amd64 go build -o companion-linux-amd64 ./cmd/agent
|
||||
|
||||
- name: Build Windows AMD64
|
||||
run: |
|
||||
cd companion-agent
|
||||
GOOS=windows GOARCH=amd64 go build -o companion-windows-amd64.exe ./cmd/agent
|
||||
|
||||
- name: Create Release
|
||||
uses: actions/gitea-release-action@v1
|
||||
with:
|
||||
files: |
|
||||
companion-agent/companion-linux-amd64
|
||||
companion-agent/companion-windows-amd64.exe
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Logs
|
||||
|
||||
```bash
|
||||
# View runner logs
|
||||
sudo journalctl -u gitea-runner -f
|
||||
|
||||
# Check runner status
|
||||
sudo systemctl status gitea-runner
|
||||
|
||||
# Restart runner
|
||||
sudo systemctl restart gitea-runner
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Runner shows offline in Gitea
|
||||
|
||||
1. Check service status: `sudo systemctl status gitea-runner`
|
||||
2. Check logs: `sudo journalctl -u gitea-runner -n 50`
|
||||
3. Verify network connectivity: `curl https://git.corrosionmgmt.com`
|
||||
4. Re-register if needed (delete `.runner` file and repeat Step 3)
|
||||
|
||||
### Docker permission errors
|
||||
|
||||
If runner can't access Docker socket:
|
||||
|
||||
```bash
|
||||
# Add your user to docker group
|
||||
sudo usermod -aG docker YOUR_USERNAME
|
||||
|
||||
# Logout and login again for group changes to take effect
|
||||
```
|
||||
|
||||
### Build fails with "command not found"
|
||||
|
||||
Ensure the label matches available Docker images:
|
||||
- `ubuntu-latest:docker://node:20-bullseye` - Has Node, but not Go/Rust
|
||||
- `golang:docker://golang:1.22` - Has Go
|
||||
- `rust:docker://rust:latest` - Has Rust
|
||||
|
||||
Or install tools on asgard host and use `runs-on: self-hosted`.
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Runner has access to Docker socket (can run privileged containers)
|
||||
- Only trusted repos should trigger builds on this runner
|
||||
- Consider using webhook secrets for production deployments
|
||||
- Runner credentials stored in `~/.runner` - keep secure
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Act Runner
|
||||
|
||||
```bash
|
||||
cd ~/gitea-runner
|
||||
./act_runner --version # Check current version
|
||||
|
||||
# Download new version
|
||||
wget https://dl.gitea.com/act_runner/NEW_VERSION/act_runner-NEW_VERSION-linux-amd64 -O act_runner.new
|
||||
chmod +x act_runner.new
|
||||
mv act_runner.new act_runner
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart gitea-runner
|
||||
```
|
||||
@@ -21,7 +21,15 @@
|
||||
|
||||
## Deployment
|
||||
|
||||
### First-time setup:
|
||||
### Architecture Note
|
||||
|
||||
**This stack runs on the PUBLIC docker host** (where Nginx Proxy Manager is).
|
||||
|
||||
The **Gitea act_runner** runs separately on **asgard** (the build server) and connects to the public Gitea instance remotely.
|
||||
|
||||
See `ASGARD-RUNNER.md` for act_runner setup instructions.
|
||||
|
||||
### First-time setup (on public docker host):
|
||||
```bash
|
||||
cd infra
|
||||
docker compose up -d
|
||||
|
||||
Reference in New Issue
Block a user