Environment_Infrastructure/setup/05-test-runner-and-deploy-prerequisites.md

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.

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

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:

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

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:

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:

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

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