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