Server configuration
For a complete deployment walkthrough, see Install the server. The server is configured through command-line flags and the two TLS environment variables below; it does not load a server YAML configuration file.
Commands
| Command | Purpose |
|---|---|
pyplines-server version | Print build version and commit information |
pyplines-server bootstrap | Create the first administrator in a new data directory |
pyplines-server migrate | Open the data directory and apply database migrations, then exit |
pyplines-server start | Start embedded NATS, the coordinator, and the HTTPS API |
--data PATH is a persistent flag available to the commands. Its default is ./.pyplines-server, relative to the process working directory. Use an absolute persistent path for a service.
Start flags
| Flag | Default | Meaning |
|---|---|---|
--data | ./.pyplines-server | Private state directory |
--listen | :8080 | HTTPS bind address; the default listens on all interfaces |
--tls-cert | PYPLINES_TLS_CERT, otherwise empty | PEM server certificate/chain |
--tls-key | PYPLINES_TLS_KEY, otherwise empty | PEM private key |
--nats-listen | :4222 | Embedded NATS TLS bind address |
--nats-url | tls://localhost:4222 | NATS URL advertised to runners |
Explicit TLS flags override the corresponding environment variables. TLS certificate and key are required for startup even though the flag parser supplies empty defaults. There is no plain-HTTP server mode.
--nats-listen chooses where the server listens; --nats-url tells runners where to connect. Configure the latter for the actual runner network. The default localhost is unsuitable for runners on another host or in a separate container.
HTTPS and NATS use the same certificate and key. Their client-visible names must be covered by that certificate. A reverse proxy must preserve API behavior; runners require an HTTPS origin without a path prefix and reject registration redirects. NATS remains a separate TLS connection.
The current server embeds its broker and database. These flags do not support replacing NATS with an external broker, selecting PostgreSQL, or starting multiple server replicas against one data directory.
Bootstrap flags
| Flag | Default | Meaning |
|---|---|---|
--username | admin | Initial administrator username |
--password-file | Required | File containing the initial password, at least 12 characters |
--if-needed | false | Create the administrator only if no users exist |
The command removes trailing CR/LF from the password file. --if-needed does not reset an existing account or password. The file must still exist and be readable when invoking bootstrap. Run bootstrap with the same data path and filesystem identity as the service, while the service is stopped.
Persistent state
Path inside --data | Contents |
|---|---|
pyplines.db and SQLite sidecar files | Platform records, revisions, access, and execution state |
encryption.key | Key needed to decrypt protected records |
logs/ | Retained filesystem log data |
nats/ | Embedded JetStream storage |
pyplines.db.lock | Exclusive process lock for the database |
Run only one server against this directory. The service user needs read/write access to state and read access to TLS files. Back up the complete stopped-service directory with its ownership and permissions; see maintenance.
The server does not need access to a Docker socket. It does need registry network access to inspect Actions at deployment/preparation time. Registry configuration and read credentials are managed through the operator API/CLI, separately from these startup flags.
Health and shutdown
GET /health returns status and version when the HTTP handler can reach the database; it returns HTTP 503 when the database check fails. It is not a check of runner admission, registry connectivity, or Action readiness. Use installation verification for those.
The process handles SIGTERM and SIGINT and allows up to ten seconds for HTTP shutdown. Stop operational work and settle runner executions before stopping the server. Certificate files are loaded at startup; apply replacements through a controlled restart rather than assuming automatic reload.
For the exact flags of an installed binary:
pyplines-server --help
pyplines-server start --help
pyplines-server bootstrap --help