Metadata-Version: 2.5
Name: pyplines-installer
Version: 2026.10.3rc1
Summary: Install and diagnose supported Pyplines server and runner deployments
Requires-Python: >=3.12
Requires-Dist: pyplines[client]==2026.10.3rc1
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.24
Description-Content-Type: text/markdown

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

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

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

```sh
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`.
