Remove deprecated Gitea runners configuration files and scripts; reorganize runner-related files into a dedicated 'runners/' directory for better structure and management; update documentation to reflect these changes.

docs/RUNNERS.md

@@ -11,6 +11,8 @@ The LabFusion project uses multiple specialized runners to handle different type
 - **Docker Runner**: Integration tests and Docker builds
 - **Security Runner**: Security scans and vulnerability assessments
 
+**Note**: All runners use the official `gitea/act_runner:nightly` image with individual configuration files. Each runner has its own data directory and configuration for better isolation and management.
+
 ## Quick Start
 
 ### 1. Prerequisites
@@ -23,6 +25,9 @@ The LabFusion project uses multiple specialized runners to handle different type
 
 **Windows PowerShell:**
 ```powershell
+# Navigate to runners directory
+cd runners
+
 # Copy the environment template
 Copy-Item env.runners.example .env.runners
 
@@ -32,6 +37,9 @@ notepad .env.runners
 
 **Linux/macOS:**
 ```bash
+# Navigate to runners directory
+cd runners
+
 # Copy the environment template
 cp env.runners.example .env.runners
 
@@ -40,37 +48,96 @@ nano .env.runners
 ```
 
 **Manual Creation (if copy fails):**
-Create `.env.runners` file with the following content:
+Create `runners/.env.runners` file with the following content:
 
 ```bash
 # 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
+GITEA_RUNNER_REGISTRATION_TOKEN=your_runner_registration_token_here
 ```
 
 **Important:** Replace `your_runner_registration_token_here` with your actual token from Gitea Admin > Actions > Runners.
 
+### 2.1. Create Configuration Files
+
+Each runner requires its own configuration file. Create the following files in the `runners/` directory:
+
+**`config_heavy.yaml`:**
+```yaml
+log:
+  level: info
+
+runner:
+  file: /data/.runner
+  capacity: 2
+  envs:
+    - JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
+    - PATH=/usr/lib/jvm/java-17-openjdk-amd64/bin:$PATH
+```
+
+**`config_light.yaml`:**
+```yaml
+log:
+  level: info
+
+runner:
+  file: /data/.runner
+  capacity: 2
+  envs:
+    - NODE_VERSION=20
+```
+
+**`config_docker.yaml`:**
+```yaml
+log:
+  level: info
+
+runner:
+  file: /data/.runner
+  capacity: 1
+```
+
+**`config_security.yaml`:**
+```yaml
+log:
+  level: info
+
+runner:
+  file: /data/.runner
+  capacity: 1
+```
+
 ### 3. Start Runners
 
 **Linux/macOS:**
 ```bash
+# Navigate to runners directory
+cd runners
+
 # Make script executable
-chmod +x scripts/manage-runners.sh
+chmod +x manage-runners.sh
 
 # Start all runners
-./scripts/manage-runners.sh start
+./manage-runners.sh start
 ```
 
 **Windows PowerShell:**
 ```powershell
+# Navigate to runners directory
+cd runners
+
 # Start all runners
-.\scripts\manage-runners.ps1 start
+.\manage-runners.ps1 start
 ```
 
 **Docker Compose directly:**
 ```bash
+# Navigate to runners directory
+cd runners
+
+# Start runners
 docker-compose -f docker-compose.runners.yml --env-file .env.runners up -d
 ```
 
@@ -100,51 +167,60 @@ Each runner is configured with specific labels for workload routing:
 
 **Linux/macOS:**
 ```bash
+# Navigate to runners directory
+cd runners
+
 # Start runners
-./scripts/manage-runners.sh start
+./manage-runners.sh start
 
 # Check status
-./scripts/manage-runners.sh status
+./manage-runners.sh status
 
 # View logs
-./scripts/manage-runners.sh logs
-./scripts/manage-runners.sh logs labfusion-runner-heavy
+./manage-runners.sh logs
+./manage-runners.sh logs labfusion-runner-heavy
 
 # Restart runners
-./scripts/manage-runners.sh restart
+./manage-runners.sh restart
 
 # Stop runners
-./scripts/manage-runners.sh stop
+./manage-runners.sh stop
 
 # Clean up (removes all data)
-./scripts/manage-runners.sh clean
+./manage-runners.sh clean
 ```
 
 **Windows PowerShell:**
 ```powershell
+# Navigate to runners directory
+cd runners
+
 # Start runners
-.\scripts\manage-runners.ps1 start
+.\manage-runners.ps1 start
 
 # Check status
-.\scripts\manage-runners.ps1 status
+.\manage-runners.ps1 status
 
 # View logs
-.\scripts\manage-runners.ps1 logs
-.\scripts\manage-runners.ps1 logs labfusion-runner-heavy
+.\manage-runners.ps1 logs
+.\manage-runners.ps1 logs labfusion-runner-heavy
 
 # Restart runners
-.\scripts\manage-runners.ps1 restart
+.\manage-runners.ps1 restart
 
 # Stop runners
-.\scripts\manage-runners.ps1 stop
+.\manage-runners.ps1 stop
 
 # Clean up (removes all data)
-.\scripts\manage-runners.ps1 clean
+.\manage-runners.ps1 clean
 ```
 
 ### Direct Docker Compose Commands
 
 ```bash
+# Navigate to runners directory
+cd runners
+
 # Start all runners
 docker-compose -f docker-compose.runners.yml up -d
 
@@ -217,29 +293,51 @@ docker system df -v
 
 ### Common Issues
 
-1. **Runners not registering / Token appears empty**
-   - **Check if `.env.runners` file exists** in the project root
+1. **"Cannot find: node in PATH" or similar tool errors**
+   - **This is handled** by the official `gitea/act_runner:nightly` image which includes necessary tools
+   - **Environment variables** can be set in the configuration files to ensure proper tool paths
+   - **Check your configuration files** to ensure proper environment setup
+
+2. **"registration file not found, please register the runner first" error**
+   - **This is handled** by the official `gitea/act_runner:nightly` image with proper configuration
+   - **The `.runner` file** is created in the `/data` directory and persists between restarts
+   - **Ensure configuration files** are properly mounted and environment variables are set
+   - **Restart the runners** if you see this error:
+     ```bash
+     cd runners
+     docker-compose -f docker-compose.runners.yml down
+     docker-compose -f docker-compose.runners.yml up -d
+     ```
+
+3. **Configuration file not found errors**
+   - **Ensure all config files exist**: `config_heavy.yaml`, `config_light.yaml`, `config_docker.yaml`, `config_security.yaml`
+   - **Check file permissions** and ensure they're readable by the container
+   - **Verify volume mounts** in the Docker Compose file are correct
+
+4. **Runners not registering / Token appears empty**
+   - **Check if `.env.runners` file exists** in the `runners/` directory
    - **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`:
      ```bash
+     cd runners
      docker-compose -f docker-compose.runners.yml --env-file .env.runners up -d
      ```
 
-2. **Runners not registering**
+5. **Runners not registering**
    - Check Gitea instance URL and port
    - Verify runner token is correct
    - Ensure Gitea Actions is enabled
 
-3. **High resource usage**
+6. **High resource usage**
    - Adjust CPU/memory limits in docker-compose.runners.yml
    - Check for stuck jobs in Gitea Actions
 
-4. **Docker socket issues**
+7. **Docker socket issues**
    - Ensure Docker socket is accessible: `/var/run/docker.sock`
    - Check Docker daemon is running
 
-5. **Network connectivity**
+8. **Network connectivity**
    - Verify runners can reach Gitea instance
    - Check firewall settings