esys-ci-host 0.2.0

Library and CLI to prepare Linux VPS hosts as GitLab CI runners

esys-ci-host

Library and CLI to prepare Linux VPS hosts as GitLab CI runners (Docker, privileged DinD, runner registration).

Extracted from the CI-host portions of esysdox-ops so LibESys superbuild and other tooling can depend on a focused package.

Install

pip install esys-ci-host

Quick start

On a fresh Ubuntu or Debian VPS (Docker executor for LibESys CI):

sudo esys-ci-host host bootstrap --yes --admin-user deploy --ssh-key-file ~/.ssh/id_ed25519.pub
# from your laptop: ssh deploy@<vps-ip>   (confirm login works)
sudo esys-ci-host host harden --yes
sudo esys-ci-host runner prepare --yes
esys-ci-host runner register --url https://gitlab.example.com --profile ci
esys-ci-host doctor

host bootstrap creates the admin user, installs OpenSSH, installs your SSH public key (or generates one under /etc/esys-ci-host/), verifies key setup, and enables UFW with SSH allowed. Root SSH stays enabled until you run host harden after confirming deploy login from your machine. Pass --ssh-key-file ~/.ssh/id_ed25519.pub or set ESYS_CI_HOST_ADMIN_SSH_PUBLIC_KEY / ESYS_CI_HOST_ADMIN_SSH_PUBLIC_KEY_FILE. Use --disable-root-ssh only if you accept lockout risk without external login verification.

Set ESYS_CI_HOST_RUNNER_TOKEN instead of passing --token when registering.

Host bootstrap

Option	Purpose
--admin-user NAME	Non-root login account with sudo (default: esysadmin)
--ssh-key KEY	OpenSSH public key line for admin login
--ssh-key-file PATH	File containing the public key
--ssh-port PORT	SSH port used for localhost login verification (default: 22)
--disable-root-ssh	Disable root SSH during bootstrap (default: keep root until host harden)
--yes	Required to apply host changes
--dry-run	Print steps without mutating the host

If no key is supplied, an ed25519 key pair is generated at /etc/esys-ci-host/<admin-user>-id_ed25519 — copy the private key securely before closing your root session.

After bootstrap: SSH in as the admin user from your machine, then run sudo esys-ci-host host harden --yes to disable root login.

Runner registration and executors

The GitLab executor is chosen at registration time (runner register), not during runner install or runner prepare.

Option	Purpose
--executor shell	Run jobs directly on the host (default)
--executor docker	Run jobs in containers (requires runner prepare)
--profile ci	LibESys CI preset: docker executor, privileged DinD, tags docker-privileged, and a sensible default image
--docker-image IMAGE	Override the runner’s default image (fallback only; see note below)
--docker-privileged	Privileged docker executor (enabled automatically by --profile ci)
--tags TAGS	Comma-separated runner tags (e.g. linux,docker)

Default image vs job image: GitLab Runner’s --docker-image (at register time) is only the fallback written into config.toml. Each CI job uses its own image: from .gitlab-ci.yml when present — you do not need to pass --docker-image for every image your pipeline uses. With --profile ci, a default (python:3.11-bookworm) is applied automatically; override it only if you want a different fallback for jobs that omit image:.

Shell executor (simple jobs on the host):

sudo esys-ci-host runner install --yes
esys-ci-host runner register --url https://gitlab.example.com --executor shell --tags shell

Docker executor (explicit; run prepare first). GitLab Runner requires a default image for non-interactive docker registration, so pass --docker-image here unless you use --profile ci:

sudo esys-ci-host runner prepare --yes
esys-ci-host runner register \
  --url https://gitlab.example.com \
  --executor docker \
  --docker-image python:3.11-bookworm \
  --docker-privileged \
  --tags docker-privileged

LibESys CI profile (recommended; includes docker executor defaults — no need to pass --docker-image unless overriding the fallback):

sudo esys-ci-host runner prepare --yes
esys-ci-host runner register --url https://gitlab.example.com --profile ci

Use --dry-run on runner register to print the gitlab-runner register command without executing it.

Development

Platform-specific host operations (packages, users, firewall, SSH) live under src/esys_ci_host/platform/. DebianAptBackend is implemented today; add new HostPlatformBackend subclasses (for example RhelDnfBackend) and register them in platform/registry.py to support additional distributions later. Runner install/prepare still use apt directly and will migrate to the platform layer in a follow-up.

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install
pre-commit install --hook-type commit-msg
pytest

Release tags vX.Y.Z must match src/esys_ci_host/__version__.py. Use make bump-release locally; CI publishes to GitLab PyPI, TestPyPI, and PyPI (manual).

Integration tests (Docker + systemd, Ubuntu 24.04 by default):

# Full runner workflow
bash tests/integration/run_docker.sh

# Host bootstrap + harden workflow
INTEGRATION_SCRIPT=/usr/local/bin/run-integration-host-bootstrap bash tests/integration/run_docker.sh

# Windows
.\test.ps1 -HostBootstrap

License

Apache-2.0 — see LICENSE.