Pyplines Installer

pyplines-installer installs the supported Docker Compose server/runner deployment on Linux with rootful Docker Engine or natively on macOS with Docker Desktop. Python 3.12+, a Linux amd64/arm64 daemon (Engine 26+), and Compose 2.24+ are required. Run it on each host being installed. Windows, remote/rootless daemons, and other macOS VM providers are not supported. It does not install Docker or modify firewalls. Individual installs require provisioned TLS/DNS; local generates development TLS.

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
# Or create both for local development (parent directory must exist):
pyplines-installer local --directory "$HOME/pyplines-local"

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 and Docker context/endpoint/daemon identity. 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 uses uv to run natively on Linux or macOS with Docker Desktop. Run it with Docker started and the repository shared with Docker. 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. A second test verifies the local profile, automatic enrollment/approval, space-containing paths, and credential-free restart with the retained certificate and identity. CI runs this on Linux; native Mac validation requires Docker Desktop and can be run using the same task. 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.

Docker Desktop and local setup

The Mac CLI socket (usually ~/.docker/run/docker.sock) and the runner's Linux VM socket (/var/run/docker.sock) are separate. No Mac socket symlink is necessary. Architecture comes from the daemon, not the host Python process. Switch back to the saved context if a retry reports docker_target_changed. Mount probes report file sharing/socket restrictions before starting services.

local publishes HTTPS on 127.0.0.1:8443 and NATS on 127.0.0.1:4222, connects services through a private bridge network, and enrolls one runner in pool local. Use --name, --api-port, --nats-port, and --platform-version at creation to change the defaults. The generated certificate lasts one year and is not added to OS trust: use ca.crt as the CLI CA file. Keep the directory and named volumes. For automation, use --password-file FILE --yes; retries after approval need no password. status/doctor --directory DIR accept the local profile root.