Metadata-Version: 2.4
Name: esys-ci-host
Version: 0.1.0
Summary: Library and CLI to prepare Linux VPS hosts as GitLab CI runners
Author-email: LibESys <ops@libesys.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.com/libesys/esys-ci-host/esys-ci-host
Project-URL: Repository, https://gitlab.com/libesys/esys-ci-host/esys-ci-host.git
Project-URL: Documentation, https://gitlab.com/libesys/esys-ci-host/esys-ci-host/-/blob/develop/README.md
Keywords: gitlab,ci,runner,docker,vps,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"
Dynamic: license-file

# 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](https://gitlab.com/libesys/esysdox-ops) so LibESys superbuild and other tooling can depend on a focused package.

## Install

```bash
pip install esys-ci-host
```

## Quick start

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

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

Set `ESYS_CI_HOST_RUNNER_TOKEN` instead of passing `--token` when registering.

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

```bash
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`:

```bash
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):

```bash
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

```bash
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).

## License

Apache-2.0 — see [LICENSE](LICENSE).
