labFusion/docs/RUNNERS.md

LabFusion Gitea Runners Setup

This document explains how to set up and manage multiple Gitea Actions runners for the LabFusion project using Docker Compose.

Overview

The LabFusion project uses multiple specialized runners to handle different types of CI/CD workloads:

• Heavy Runner: Java Spring Boot (API Gateway) and Python FastAPI (Service Adapters)
• Light Runner: Node.js (API Docs) and React (Frontend)
• Docker Runner: Integration tests and Docker builds
• Security Runner: Security scans and vulnerability assessments

Quick Start

1. Prerequisites

• Docker and Docker Compose installed
• Gitea instance running
• Runner registration token from Gitea

2. Configuration

Windows PowerShell:

# Copy the environment template
Copy-Item env.runners.example .env.runners

# Edit the configuration
notepad .env.runners

Linux/macOS:

# Copy the environment template
cp env.runners.example .env.runners

# Edit the configuration
nano .env.runners

Manual Creation (if copy fails): Create .env.runners file with the following content:

# Gitea instance URL (adjust port if different)
GITEA_INSTANCE_URL=http://localhost:3000

# Runner registration token (get from Gitea Admin > Actions > Runners)
GITEA_RUNNER_TOKEN=your_runner_registration_token_here

Important: Replace your_runner_registration_token_here with your actual token from Gitea Admin > Actions > Runners.

3. Start Runners

Linux/macOS:

# Make script executable
chmod +x scripts/manage-runners.sh

# Start all runners
./scripts/manage-runners.sh start

Windows PowerShell:

# Start all runners
.\scripts\manage-runners.ps1 start

Docker Compose directly:

docker-compose -f docker-compose.runners.yml --env-file .env.runners up -d

Runner Configuration

Resource Allocation

Runner	CPU	Memory	Use Case
Heavy	4 cores	8GB	Java/Python builds
Light	2 cores	4GB	Node.js/Frontend
Docker	6 cores	12GB	Integration tests
Security	2 cores	4GB	Security scans

Labels

Each runner is configured with specific labels for workload routing:

• Heavy Runner: ubuntu-latest,self-hosted,heavy,java,python
• Light Runner: ubuntu-latest,self-hosted,light,nodejs,frontend
• Docker Runner: ubuntu-latest,self-hosted,docker,integration
• Security Runner: ubuntu-latest,self-hosted,security,scan

Management Commands

Using the Management Scripts

Linux/macOS:

# Start runners
./scripts/manage-runners.sh start

# Check status
./scripts/manage-runners.sh status

# View logs
./scripts/manage-runners.sh logs
./scripts/manage-runners.sh logs labfusion-runner-heavy

# Restart runners
./scripts/manage-runners.sh restart

# Stop runners
./scripts/manage-runners.sh stop

# Clean up (removes all data)
./scripts/manage-runners.sh clean

Windows PowerShell:

# Start runners
.\scripts\manage-runners.ps1 start

# Check status
.\scripts\manage-runners.ps1 status

# View logs
.\scripts\manage-runners.ps1 logs
.\scripts\manage-runners.ps1 logs labfusion-runner-heavy

# Restart runners
.\scripts\manage-runners.ps1 restart

# Stop runners
.\scripts\manage-runners.ps1 stop

# Clean up (removes all data)
.\scripts\manage-runners.ps1 clean

Direct Docker Compose Commands

# Start all runners
docker-compose -f docker-compose.runners.yml up -d

# Check status
docker-compose -f docker-compose.runners.yml ps

# View logs
docker-compose -f docker-compose.runners.yml logs -f

# Stop runners
docker-compose -f docker-compose.runners.yml down

# Remove everything (including volumes)
docker-compose -f docker-compose.runners.yml down -v

Workflow Configuration

To use specific runners in your workflows, update the runs-on field:

# .gitea/workflows/api-gateway.yml
jobs:
  test:
    runs-on: [self-hosted, heavy]  # Uses heavy runner

# .gitea/workflows/frontend.yml
jobs:
  test:
    runs-on: [self-hosted, light]  # Uses light runner

# .gitea/workflows/integration-tests.yml
jobs:
  integration:
    runs-on: [self-hosted, docker]  # Uses docker runner

Monitoring

Health Checks

Each runner includes health checks that monitor:

• Container status
• HTTP health endpoint
• Resource usage

Logs

View logs for troubleshooting:

# All runners
docker-compose -f docker-compose.runners.yml logs -f

# Specific runner
docker-compose -f docker-compose.runners.yml logs -f labfusion-runner-heavy

Resource Monitoring

# Container resource usage
docker stats

# Volume usage
docker system df -v

Troubleshooting

Common Issues

1. Runners not registering / Token appears empty

   • Check if .env.runners file exists in the project root
   • Verify the file contains your actual token (not the placeholder)
   • Make sure you're using the management scripts (they include --env-file parameter)
   • If running Docker Compose directly, add --env-file .env.runners:

     docker-compose -f docker-compose.runners.yml --env-file .env.runners up -d
     

2. Runners not registering

   • Check Gitea instance URL and port
   • Verify runner token is correct
   • Ensure Gitea Actions is enabled

3. High resource usage

   • Adjust CPU/memory limits in docker-compose.runners.yml
   • Check for stuck jobs in Gitea Actions

4. Docker socket issues

   • Ensure Docker socket is accessible: /var/run/docker.sock
   • Check Docker daemon is running

5. Network connectivity

   • Verify runners can reach Gitea instance
   • Check firewall settings

Debug Mode

Enable debug logging by adding to .env.runners:

# Enable debug logging
ACTIONS_RUNNER_DEBUG=1

Reset Runners

If runners become unresponsive:

# Stop and remove all runners
docker-compose -f docker-compose.runners.yml down -v

# Clean up volumes
docker volume prune -f

# Restart
docker-compose -f docker-compose.runners.yml up -d

Security Considerations

• Runners run with Docker socket access for container builds
• Each runner has isolated data volumes
• Shared cache volume for build optimization
• Resource limits prevent resource exhaustion
• Health checks ensure runner availability

Scaling

To add more runners:

1. Copy a runner service in docker-compose.runners.yml
2. Update the runner name and labels
3. Adjust resource allocation
4. Restart the compose stack

Example additional runner:

gitea-runner-additional:
  image: gitea/act_runner:latest
  container_name: labfusion-runner-additional
  environment:
    - GITEA_INSTANCE_URL=${GITEA_INSTANCE_URL}
    - GITEA_RUNNER_REGISTRATION_TOKEN=${GITEA_RUNNER_TOKEN}
    - GITEA_RUNNER_NAME=labfusion-runner-additional
    - GITEA_RUNNER_LABELS=ubuntu-latest,self-hosted,additional
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - runner-data-additional:/data
    - shared-cache:/cache
  restart: unless-stopped

Support

For issues with the runners setup:

1. Check the troubleshooting section above
2. Review runner logs
3. Verify Gitea Actions configuration
4. Check Docker and Docker Compose installation