============================================================
  STEP-BY-STEP GUIDE: REGISTER & CONFIGURE FORGEJO RUNNER
============================================================

This guide walks you through the entire process: obtaining a registration
token, registering the runner, generating a configuration file, and
launching the runner with Docker Compose. All placeholders are clearly
marked so you can replace them with your own values.

----------------------------------------------------------------
STEP 1: OBTAIN A REGISTRATION TOKEN FROM FORGEJO
----------------------------------------------------------------

1. Open your Forgejo instance in a browser (e.g., http://YOUR_FORGEJO_URL).
2. Log in as an administrator.
3. Navigate to: Site Administration → Actions → Runners.
4. Click the "Create Runner" button.
5. Copy the generated token. It will look like a long alphanumeric string.

   Example placeholder: YOUR_REGISTRATION_TOKEN

----------------------------------------------------------------
STEP 2: REGISTER THE RUNNER (CREATE .runner FILE)
----------------------------------------------------------------

Create a working directory and register the runner using the Docker image.

mkdir -p ~/forgejo-runner
cd ~/forgejo-runner

mkdir -p data cache

Run the registration command, replacing the placeholders:

docker run -it --rm \
  -v $(pwd)/data:/data \
  -w /data \
  --user root \
  data.forgejo.org/forgejo/runner:4.0.0 \
  forgejo-runner register \
  --no-interactive \
  --token YOUR_REGISTRATION_TOKEN \
  --name YOUR_RUNNER_NAME \
  --instance http://YOUR_FORGEJO_URL \
  --labels YOUR_LABEL

Placeholder explanations:
  YOUR_REGISTRATION_TOKEN  – the token you copied from Forgejo
  YOUR_RUNNER_NAME         – a name you choose (e.g., "websites")
  YOUR_FORGEJO_URL         – the URL of your Forgejo instance (e.g., "192.168.2.76:3000")
  YOUR_LABEL               – one or more labels (e.g., "websites" or "ubuntu-latest,self-hosted")

After success, a file data/.runner is created. This stores the runner's
permanent credentials.

Verify:
ls -la data/.runner

----------------------------------------------------------------
STEP 3: GENERATE AND CONFIGURE config.yaml
----------------------------------------------------------------

If you don't already have a config.yaml, generate the default one:

docker run --rm \
  -v $(pwd)/data:/data \
  -w /data \
  data.forgejo.org/forgejo/runner:4.0.0 \
  forgejo-runner generate-config > data/config.yaml

Now open data/config.yaml and customize it. Below is a complete example
based on a typical setup. Replace all placeholders (marked with YOUR_*)
with your actual values.

----------------------------------------------------------------
EXAMPLE config.yaml (customizable)
----------------------------------------------------------------

# --------------------------- REQUIRED ---------------------------
# The URL of your Forgejo instance
instance: http://YOUR_FORGEJO_URL

# The runner token (can be the registration token or the token from .runner)
token: "YOUR_RUNNER_TOKEN"

# --------------------------- LOGGING ---------------------------
log:
  level: info                # options: trace, debug, info, warn, error, fatal

# --------------------------- RUNNER SETTINGS ---------------------------
runner:
  file: .runner              # path to registration file (relative to /data)
  capacity: 1                # number of concurrent tasks
  timeout: 30m               # max job duration (customize as needed)
  shutdown_timeout: 30m      # graceful shutdown timeout
  insecure: true             # set to true if using HTTP (skip TLS verification)
  fetch_timeout: 30s
  fetch_interval: 60s
  report_interval: 10s

  # Labels determine which jobs this runner picks up.
  # Format: "label:executor". Executor can be "host" (run on host) or "docker://image".
  # The label(s) must match the `runs-on` value in your workflows.
  labels:
    - "YOUR_LABEL:host"      # e.g., "websites:host"

# --------------------------- CACHE ---------------------------
cache:
  enabled: true
  dir: ""                    # leave empty to use default $HOME/.cache/actcache

# --------------------------- CONTAINER EXECUTOR OPTIONS ----------------
container:
  # Set privileged to true if your workflows need Docker-in-Docker.
  # If you use a separate docker-in-docker service, you can keep it false.
  privileged: false
  # Allow mounting any volume (useful for host directories)
  valid_volumes:
    - '**'
  docker_host: ""            # auto-detect; you can override with environment variable DOCKER_HOST
  force_pull: false

# --------------------------- HOST EXECUTOR OPTIONS --------------------
host:
  workdir_parent: ""         # parent directory for job workspaces (default ~/.cache/act/)

---

Save the file. The most important fields to adjust are:
- instance
- token (or remove after registration)
- runner.labels (must match your workflow's `runs-on`)
- container.privileged (set to true if you run docker commands inside jobs)

----------------------------------------------------------------
STEP 4: CREATE DOCKER-COMPOSE.YML
----------------------------------------------------------------

Create a docker-compose.yml file in the same directory (~/forgejo-runner)
with the following content. Replace YOUR_LABEL and any host paths.

---
version: '3.8'

services:
  docker-in-docker:
    image: docker:dind
    container_name: docker_dind
    privileged: true
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: unless-stopped

  runner:
    image: data.forgejo.org/forgejo/runner:4.0.0
    container_name: runner
    depends_on:
      docker-in-docker:
        condition: service_started
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 0:0                                 # run as root to avoid permission issues
    volumes:
      - ./data:/data                          # config and .runner
      - ./cache:/cache                        # optional cache directory
      # Mount any host directories your workflows need to access:
      # - /host/path:/container/path
      # Example mounts (uncomment and adjust):
      # - /var/www/YOUR_PROJECT:/var/www/YOUR_PROJECT
      # - /home/user/shared:/shared
    restart: unless-stopped
    command: /bin/sh -c "
      apk update && apk add --no-cache nodejs npm &&
      sleep 5 &&
      forgejo-runner daemon --config /data/config.yaml
      "
---

Note: The command installs Node.js and npm – required for actions like
actions/checkout. If you prefer a custom image with Node.js pre-installed,
you can build one, but this method works fine.

----------------------------------------------------------------
STEP 5: START THE RUNNER
----------------------------------------------------------------

Launch all services in detached mode:

docker compose up -d

Check the logs to confirm everything is running:

docker compose logs -f runner

Expected output:
  "runner: YOUR_RUNNER_NAME, with version: v4.0.0, with labels: [YOUR_LABEL], declared successfully"
  "[poller 0] launched"

If you see errors, review the logs and verify your config.

----------------------------------------------------------------
STEP 6: TEST WITH A SAMPLE WORKFLOW
----------------------------------------------------------------

Create a test workflow in any repository on your Forgejo instance.
Place the file at: .forgejo/workflows/test.yml

---
on: [push]
jobs:
  test:
    runs-on: YOUR_LABEL               # must match the label you registered
    steps:
      - name: Hello
        run: echo "Runner is alive!"
      - name: Check Node.js
        run: node --version
      - name: Check Docker
        run: docker info
---

Commit and push the file. The runner should pick up the job automatically.

Watch the logs to see the job progress:

docker compose logs -f runner

----------------------------------------------------------------
TROUBLESHOOTING COMMON ISSUES
----------------------------------------------------------------

| Symptom                            | Solution                                                                 |
|------------------------------------|--------------------------------------------------------------------------|
| "permission denied" on .runner     | Use --user root in registration or set user: 0:0 in docker-compose.      |
| "cannot find node"                 | Ensure Node.js is installed (the command above adds it).                 |
| Runner stays idle                  | Check that the label in your workflow exactly matches the runner's label.|
| "invalid token"                    | Generate a new token in Forgejo admin and re-register.                   |
| Docker errors in jobs              | Verify DOCKER_HOST=tcp://docker-in-docker:2375 is set.                   |

----------------------------------------------------------------
QUICK REFERENCE – PLACEHOLDERS USED IN THIS GUIDE
----------------------------------------------------------------

| Placeholder                | Description                                                               |
|----------------------------|---------------------------------------------------------------------------|
| YOUR_FORGEJO_URL           | The IP/hostname and port of your Forgejo instance (e.g., 192.168.2.76:3000) |
| YOUR_REGISTRATION_TOKEN    | The one-time token from Forgejo admin → Actions → Runners → Create Runner |
| YOUR_RUNNER_NAME           | A friendly name for the runner (appears in admin UI)                     |
| YOUR_LABEL                 | Label used in workflows (e.g., "websites" or "ubuntu-latest")            |
| YOUR_RUNNER_TOKEN          | The permanent token (usually the same as registration, or taken from .runner) |

----------------------------------------------------------------
END OF GUIDE
----------------------------------------------------------------