corrosion-admin-panel/infra/ASGARD-RUNNER.md

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

   docker --version
   

2. Go installed (already present per Commander)

   go version
   

3. Rust installed (already present per Commander)

   rustc --version
   

---

Installation Steps

Step 1: Download act_runner Binary

On asgard, download the latest act_runner:

# 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:

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:

sudo nano /etc/systemd/system/gitea-runner.service

Service file contents:

[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

# 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:

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:

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

# 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:

# 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

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