Overview and requirements
Installation is for administrators setting up Pyplines. Engineers joining an existing installation can start with Run your first workflow.
For a first evaluation, use the local evaluation guide. For a shared installation, follow Install the server, Install a runner, and Verify the installation.
The guided installer automates the Compose deployment and retains a repeatable configuration. Check its package availability and host requirements before choosing it; the manual guides remain available for both Compose and native Linux services.
Choose a layout
| Layout | How it works |
|---|---|
| Guided local setup | pyplines-installer run with the local profile on Linux or macOS with Docker Desktop; private server/runner network and development TLS |
| Local evaluation | Published server and runner images, a local registry, and locally trusted certificates on one Docker host |
| Shared installation, one host | One server and one or more runners on the same Linux host, using the container or Linux service instructions |
| Separate hosts | One server host and dedicated runner hosts; each runner uses its own local Docker daemon and persistent state |
Run one server process per installation. The current server owns SQLite and embedded NATS JetStream state; these instructions do not describe an HA cluster or an external database/broker deployment. Runners provide execution capacity, not replicas of the server. See architecture.
The container guides use separate Compose files for server and runner. You can use both on one host or place them on different hosts. Both layouts use a DNS name that resolves from the administrator workstation and every runner; they do not depend on cross-host Compose service discovery.
Choose releases
Obtain the server and runner from the same platform release. Install the operator CLI from the supported tooling release. Platform and tooling versions can differ; use the supported combination shown by this documentation site.
The examples use these shell variables. Replace the placeholder values with actual published tags before running commands:
export PLATFORM_TAG='platform/YYYY.M.RELEASE'
export TOOLING_TAG='tooling/YYYY.M.RELEASE'
export PLATFORM_VERSION="${PLATFORM_TAG##*/}"
export TOOLING_VERSION="${TOOLING_TAG##*/}"
Keep any rcN suffix. Historical combined releases have a bare tag such as 2026.10.1rc17; use that exact tag when selecting one. Image and Python package versions always omit the group prefix. Published server/runner images are ghcr.io/pyplines/pyplines-server:$PLATFORM_VERSION and ghcr.io/pyplines/pyplines-runner:$PLATFORM_VERSION. There is no latest alias.
Host and storage requirements
| Component | Requirements |
|---|---|
| Server | Linux amd64 or arm64, persistent private storage, a DNS name, TLS certificate and key, access to the Action registry |
| Runner | Linux amd64 or arm64, a local Docker daemon supporting named-volume subdirectory mounts, persistent state/work storage, access to server HTTPS, server NATS TLS, and the Action registry |
| Administrator workstation | Python 3.12+, the operator CLI, HTTPS access to the server; GitHub CLI for the binary download examples |
| Action registry | An OCI registry reachable by both the server and runners, containing the Action images your workflows use |
On macOS, the guided local profile runs the installer natively while server, runner, and Action containers execute in Docker Desktop’s Linux VM.
Containers require Docker Engine with the Compose plugin; Linux service examples assume a systemd host. Runner examples use a rootful local Docker daemon and run the runner as root because it stages files for Action UID 65532 and controls Docker. The server service runs as a dedicated unprivileged account and needs no Docker socket. Action containers do not receive that socket.
Size hosts for your workload. Each runner defaults to one concurrent Action and can be configured for up to 64; the resources required depend on the Actions. Monitor server data/log usage, runner work storage, and Docker image usage. There is no documented universal minimum CPU/RAM sizing or automatic storage expansion.
Persist the complete server data directory and each runner's state. Use a unique state directory and work volume per runner identity. Do not share one runner's state across hosts or start multiple runners against it.
Network and TLS plan
The shared-installation examples use pyplines.example.com as a placeholder:
| Source | Destination | Purpose |
|---|---|---|
| Administrator and operator clients | https://pyplines.example.com:8080 | Login and platform API |
| Runners | https://pyplines.example.com:8080 | Enrollment and registration status |
| Runners | tls://pyplines.example.com:4222 | Authenticated fleet transport, assignments, and execution reporting |
| Server and runners | Your Action registry | Image inspection and pulls |
| Network-enabled Actions | Their configured target services | The operation the Action performs |
Allow the two server ports from the appropriate networks. Runners initiate their connections; they do not require an inbound Pyplines service port. A reverse proxy for HTTPS does not automatically proxy NATS. Preserve a separately reachable NATS TLS endpoint if you change the API's public port.
The server uses the same certificate and key for HTTPS and NATS. Its certificate must cover every hostname used for those endpoints, and runners must trust its CA. In the guides, provision server.crt (certificate chain), server.key, and ca.crt (public issuing CA). Never copy a CA private key to the services. For publicly trusted certificates, the extra CA configuration can be omitted.
On separate hosts, localhost in the advertised NATS URL points to each runner itself and will not work. On one host, the hostname must still resolve correctly from inside the runner container.
Continue
- Install and bootstrap the server.
- Install, enroll, and approve a runner.
- Configure an Environment and verify execution.
- Establish access policies and backups before operational use.