Pyplines Installer

pyplines-installer installs the supported Docker Compose server/runner deployment on Linux amd64/arm64. Python 3.12+, rootful Docker Engine 26+, Compose 2.24+, a local /var/run/docker.sock, and provisioned TLS/DNS are prerequisites. Run it on each host being installed. It does not install Docker, issue certificates, or modify firewalls.

Installation and use

After its first tooling release is published:

pipx install pyplines-installer
pyplines-installer version
pyplines-installer install server
pyplines-installer install runner

pip install pyplines-installer in a virtual environment is also supported. Interactive installation collects missing settings and shows a plan before applying. For automation, use a complete configuration and private credential files:

pyplines-installer install --config installation.yaml --dry-run
pyplines-installer install --config installation.yaml --password-file ./password --yes
pyplines-installer --json status --directory ./installation
pyplines-installer doctor --directory ./installation

Use --enrollment-token-file for a runner. Files must be private (chmod 600). Enrollment and approval are administered through the existing pyplines operator CLI. The installer reports pending approval separately from readiness. Return codes are 0 for success, 1 for operation/configuration failures, and 2 for not-ready state or CLI argument errors. --json must precede the command and disables prompting.

The complete guide is in docs/content/3.installation/7.installer.md, with command reference in docs/content/9.reference/10.installer-cli.md. The authoritative configuration schema lives at contracts/installation/v1/installation.schema.json. It is bundled with the package; validation does not fetch remote schemas.

Persistence and retry behavior

A private installation directory records configuration, Compose, ownership, and the resolved image digest. Named Docker volumes hold service data. Repeat the saved configuration to resume; unmanaged resources, configuration changes, and Compose file drift are rejected. Never remove volumes to resolve an installation error. Bootstrap credentials are copied temporarily and removed; enrollment tokens are removed after registration is saved. Original credential files remain your responsibility.

The installer version follows tooling tags. Its packaged default platform version comes from releases/supported.json; explicit versions remain possible. Installing an updated installer does not upgrade the server or runner. Both components must use the same platform version. Server releases must support retry-safe bootstrap --if-needed. Existing deployments are not automatically adopted. Native systemd setup, upgrades, rollback, and uninstall are not implemented.

Development and verification

From the repository root:

uv run --project pyplines-installer pyplines-installer --help
uv run --project pyplines-installer python -m unittest discover -s pyplines-installer/tests
uv build pyplines-installer
task contracts:generate
task contracts:check
task installer:integration

The integration task runs in a Linux container with access to the local Docker socket and the repository mounted at its original absolute path. It uses ports 29443, 24222, and 25129, builds disposable candidate images, and checks bootstrap, TLS, enrollment/approval, echo Action execution, retries, and state-preserving restarts. Unique test containers/volumes/networks are removed in finally; image build caches and the reusable test images remain. The test version is a fixture, not a claim that locally built bytes are a published release.

Tooling publication builds wheel/sdist artifacts and verifies isolated installs. Configure the PyPI Trusted Publisher for project pyplines-installer, owner pyplines, repository pyplines, workflow publish-tooling.yml, environment pypi.