# 05 - Test Runner and Deploy Prerequisites

The purpose of this phase is to install the Gitea Actions runner (`act_runner`) as a systemd service in the test environment and prepare the environment where CI/CD pipelines can run.

## Runner Placement

A single runner is used in the test environment for cost and simplicity:

| Host | Service Name | System User | Labels |
| --- | --- | --- | --- |
| `iklim-app-01` | `gitea-act-runner` | `gitea-runner` | `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04`, `test-runner:docker://catthehacker/ubuntu:act-22.04` |

## 1. Runner User and Permissions

The runner must be able to run Docker commands on the host.

```bash
# Create the user
sudo useradd -m -s /bin/bash gitea-runner
# Add to the Docker group
sudo usermod -aG docker gitea-runner
```

## 2. act_runner Installation

### Installation

Installation and registration are done automatically with Ansible (`test-app-post-stack.yml`). If manual installation is required:

```bash
wget -O act_runner https://dl.gitea.com/act_runner/0.2.12/act_runner-0.2.12-linux-amd64
sudo mv act_runner /usr/local/bin/
sudo chmod +x /usr/local/bin/act_runner
```

### Registration

Get the **Registration Token** from the Gitea UI (Organization -> Settings -> Actions -> Runners) and add it to the vault:

```yaml
# group_vars/all/vault.yml
vault_gitea_runner_token: "<TOKEN>"
```

```bash
cd Environment_Infrastructure/ansible/test
ansible-playbook test-app-post-stack.yml --vault-password-file=.vault_pass
```

## 3. Systemd Service and Configuration

Managed by Ansible. The service file is located at `/etc/systemd/system/gitea-act-runner.service`, and the configuration is located at `/etc/gitea-act-runner/config.yaml`.

Critical parts of the configuration:

```yaml
runner:
  labels:
    - "ubuntu-latest"
    - "ubuntu-22.04"
    - "ubuntu-20.04"
    - "test-runner:docker://catthehacker/ubuntu:act-22.04"

container:
  network: "bridge"
  options: "-v /mnt/storagebox:/mnt/storagebox"
  docker_host: "unix:///var/run/docker.sock"
```

Status check:
```bash
sudo systemctl status gitea-act-runner
sudo journalctl -u gitea-act-runner -f
```

## 4. Deploy Prerequisites

The following tools must be installed for the pipeline to deploy successfully on `iklim-app-01`:
- `docker-ce` and `docker-compose-plugin`
- `gettext` for the `envsubst` command
- `jq`
- `git`

## 5. Gitea Organization Secrets

The following secrets must be defined at Gitea Organization level for pipelines to run:

| Secret | Description |
| --- | --- |
| `STORAGEBOX_SSH_PRIV` | StorageBox SSH private key |
| `STORAGEBOX_SSH_PUB` | StorageBox SSH public key |
| `HARBOR_CI_TOKEN` | `robot-ci-push-iklimco` robot account token (build + push) |
| `HARBOR_PULL_TOKEN` | `robot-swarm-pull-iklimco` robot account token (Swarm deploy pull) |
| `REPO_ACCESS_TOKEN` | Gitea private repo access (BE-Commons, etc. checkout) |

## 6. Custom Image Build and Harbor Push

Environment stack files and microservice stacks use private images under `registry.tarla.io/iklimco/`. These images are built and pushed to the registry with the `ops/push-harbor-custom-images.sh` script.

APISIX config files (`build/apisix-core/config.yaml`, `build/apisix-dashboard/conf.yaml`) are generated from templates under `template/` with `envsubst`. `push-harbor-custom-images.sh` performs this generation internally; temporary files are cleaned automatically when the build finishes.

**Design note:** The APISIX admin key is not baked into the image. The template uses `${{APISIX_ADMIN_KEY}}` (double curly braces); APISIX reads it from the Docker service environment variable when the container starts. This allows one image to be used for both test and prod.

### Steps

```bash
# 1. Log in to Harbor
docker login registry.tarla.io -u robot-ci-push-iklimco

# 2. Build and push the images; the script generates envs and config files itself
bash ops/push-harbor-custom-images.sh
```

## Acceptance Criteria

1. The runner labeled `test-runner` appears as **Idle** (green) on the Gitea Runners page.
2. A workflow using `runs-on: test-runner` is triggered successfully.
3. The job can access the Docker daemon through `docker_host`, and deploy workflows connect job containers to `iklimco-net` when overlay access is required.
4. The `8200/tcp` (Vault) port is closed to the public internet.
5. `registry.tarla.io/iklimco/custom-apisix`, `custom-apisix-dashboard`, and `custom-prometheus` images exist in Harbor and are pullable.