The .pl.yaml manifest
This page shows you how to describe your app to Pushleft in a .pl.yaml file: its roles, databases, secrets and routes. Put the file at the root of your checkout, check it with pl plan and deploy it with pl up.
Quick start
-
Sign in once with
pl login(authentication). -
Save this file as
.pl.yamlnext to yourDockerfile. It runs one web role on port 8080 with a PostgreSQL database, one secret and a custom domain:version: 1 project: shop roles: web: kind: web port: 8080 health: /healthz secrets: [STRIPE_KEY] databases: [shop] route: { domains: [shop.example.com] } data: postgres: plan: starter databases: [{ name: shop }] -
Check the manifest.
pl planrefuses an unknown field or a value outside its limits, and prints the resolved manifest:pl plan -
Store the secret for this branch’s preview environment. The value is read from standard input:
printf '%s' "$STRIPE_KEY" | pl secrets set STRIPE_KEY -
Deploy.
pl upbuilds the image, creates the database and follows the events until the URL is live:pl upThe container gets
DATABASE_URL(andPGHOST,PGUSERand the otherPG*variables) and the file/run/secrets/STRIPE_KEY. -
Claim the domain and create the DNS record that the command prints. The route serves the domain when the record is verified (custom domains):
pl domain add shop.example.com -
For production, set the secret there and deploy with
--production:pl secrets set STRIPE_KEY --production < stripe.key pl domain add shop.example.com --production pl up --production
An AI agent can write the manifest and a non-root Dockerfile for you (onboard with an AI agent).
Parsing rules
pl plan validates .pl.yaml and prints it. pl up sends it with the source. Without a .pl.yaml, a root Dockerfile gives one web role on port 8080 with health /healthz.
The parser refuses unknown fields everywhere. It checks every limit below when it parses the manifest. The node agent checks them again before a container starts.
Example
version: 1
project: orbit
build: { dockerfile: ops/docker/rust.Dockerfile, target: api }
env: { RUST_LOG: info } # every role
secrets: [ORBIT_MASTER_KEY] # every role, as /run/secrets/ORBIT_MASTER_KEY
roles:
release:
kind: release # runs once, before web starts
command: orbit migrate
databases: [orbit, orbit_audit]
web:
kind: web
command: [orbit, serve, --port, "8410"] # exec form, no shell
port: 8410
health: /api/health
env: { ORBIT_ENVIRONMENT: production }
secrets: [{ name: ORBIT_JWT_KEY, as: env }]
databases: [orbit, orbit_audit]
volumes: [{ name: orbit-state, size: 5GiB, mount: /home/orbit/.orbit }]
tmpfs: [{ path: /var/cache/orbit, size: 64MiB }]
resources: { cpu: 1, memory: 1GiB }
startup_timeout: 300
data:
postgres:
plan: starter
databases: [{ name: orbit }, { name: orbit_audit, owner_login: orbit_audit_app }]
production:
regions: [fsn1]
health: /api/health
Top level
| Field | Meaning |
|---|---|
version | 1 (the default). |
project | DNS-safe slug, no --, or the project’s id (see Projects). One project per image. |
build | Optional. dockerfile (default Dockerfile), context (default .), target (a stage name). Paths are relative to the checkout root and stay inside it: no leading /, no .., no empty segments. The build agent passes them to BuildKit as --local context=, --local dockerfile= (the Dockerfile’s directory), --opt filename= and --opt target=. test (a stage name) is built first, in the same build container. If it fails, the deployment fails with build_test_failed and nothing is published. If it passes, the image build reuses its layers. args (at most 32) sets Dockerfile ARG values, passed as --opt build-arg:NAME=value. Use it for build-time configuration such as a frontend’s API URL. Args are not secret: they land in the image and the build log. |
image | Optional, an alternative to build: deploy an image from the Pushleft registry without building, pinned by digest: organizations/<org>/<repo>@sha256:<64 hex> or proxy/<org>/<upstream>/<path>@sha256:... (<org> is the organization’s UUID, as pl registry info prints it), optionally with the registry host in front. Only images in your own organization’s namespaces, and only when the organization may deploy images (registry.md). |
env | Plain variables for every role. A role’s own env wins for the same name. A configuration set wins over both. |
secrets | Environment secrets for every role (see Secrets). A role entry with the same name replaces the top-level one. |
roles | At least one role (see Roles). |
data | postgres, clickhouse and valkey (see Databases). data.volumes is parsed but not executed. Use role volumes. |
domains, network, observability, production | Custom domains, published ports, telemetry retention and web analytics, and regions, strategy and default health path. |
turnstile | Optional. A Cloudflare Turnstile widget for the environment, with its keys as two environment secrets (see Turnstile). |
preview | Optional. region sets the region every preview of the project runs in (default fsn1). Use it for nodes your organization owns, such as an on-premises lab: preview: { region: lab1 }. See Preview region. |
Roles
| Field | Meaning |
|---|---|
kind | web, private, worker, cron, job or release. Default from the role name (web, worker, cron, job, release), else private. |
command | Replaces the image’s ENTRYPOINT and CMD. A string is shell form: the agent runs --entrypoint /bin/sh with -c <command>. So the image needs /bin/sh, and $VARIABLES expand. A list is exec form: the first item is the entrypoint and the rest are its arguments, with no shell. Use it for distroless images. Without command, the image’s own ENTRYPOINT/CMD run unchanged. |
port | The port the role listens on (≥ 1024; web requires one). pl plan and placement refuse a lower one. The container gets PORT. |
health | HTTP path probed inside the environment network, or tcp: healthy once a TCP connect to port succeeds, for a role that does not speak HTTP (SMTP, TURN, NATS). Defaults to production.health when a port is set. |
replicas | 1 to 64. A role that writes a volume runs exactly 1. |
cron | { schedule: "*/5 * * * *" }, five fields, UTC. |
env | Plain variables: names [A-Za-z_][A-Za-z0-9_]{0,127}, values up to 4 KiB without NUL, at most 128. PORT and names starting with PUSHLEFT_ are reserved. A change is a new plan, so a new release. |
secrets | Names of environment secrets (see Secrets). |
databases | Names from data.<engine>.databases; their connection variables are injected (see Databases). |
volumes | Persistent host-local volumes (application volumes). On each release, the writer of a volume stops before its replacement starts. This gives a short gap and never two releases writing. Several roles may write one volume when each sets shared: true with the same size (shared writers). A writer’s size is a floor: a larger size grows the volume online on the next deployment, and a smaller one is ignored. Shrink with pl volume resize (resize). |
tmpfs | Up to 8 writable in-memory mounts: { path, size }, size 16MiB to 1GiB. Paths are normalized and absolute, outside /proc, /sys, /dev, /etc and /run/secrets, and not a volume mount. Every mount is noexec,nosuid,nodev and mode 1777, like /tmp, so an image whose user is not root can write it. Declaring /tmp replaces the default 64 MiB /tmp. tmpfs pages count against the role’s memory, so declared mounts plus /tmp may use at most half of it. |
resources | { cpu, memory }. cpu is 0.25, 0.5, 1, 2 or 4; memory is 256MiB, 512MiB, 1GiB, 2GiB, 4GiB, 8GiB, 16GiB or 32GiB. Default 0.5 CPU and 512 MiB. On a paid plan, any of these values is allowed and billed. On the self-hosted plan, the organization’s trust tier caps them (new: 1 CPU, 1 GiB; standard: 2 CPUs, 4 GiB; trusted: 4 CPUs, 8 GiB), and an operator can set a per-organization override (abuse.md). Placement reserves exactly this on a node. A role larger than every application node is refused at once. |
user | Optional numeric uid:gid that overrides the image’s user, passed as --user. Use it for an image that starts as root and then switches users, which needs capabilities no role gets (nginx: user: "101:101"). Without it, the role runs as the image’s USER (run as a non-root user). |
image | Optional. Run this role from another image of your organization’s registry, pinned by digest, in place of the release image: organizations/<org>/...@sha256:... or proxy/<org>/...@sha256:... (a second image). |
run_as | run_as: root # reason: the role may run as root. The comment after # is the reason, up to 200 characters, and is required. Use it only when no non-root user works (run as a non-root user). |
startup_timeout | Seconds a new instance may take to pass its first health check, 10 to 600 (default 60). Missing it is a permanent failure. |
route | Web roles only: { hostname, path, domains, max_body, timeout, allow_from, headers, redirects, min_tls }, all optional (see Routes). |
egress | internet (default) or platform: where the role’s own connections may go (outbound access). |
certificates | Up to 4 hostnames. Pushleft gets a Let’s Encrypt certificate for each and puts it in the role (certificates for raw ports). |
To run a command or open a shell in a running role, use pl exec or the console’s Shell button. To reach a role’s port from your machine, use pl tunnel (developer access). No container needs an SSH server.
Every container gets the same hardening, whatever the manifest says (workload hardening):
- a digest-pinned image, a read-only root, no capabilities and
no-new-privileges; - container root remapped to an unprivileged host uid;
- no host network, no Docker socket and no Docker-published ports (Pushleft’s own nftables forwards declared published ports);
- no host paths other than its declared volumes and its own read-only secret directory.
A second image
A role can run another image beside your app, in the same environment: a vendor service, a renderer, a search engine. Name it on the role with image:, pinned by digest, from your organization’s registry namespaces. Push it there, or pull it through proxy/<org>/... (registry).
roles:
web:
port: 8080
pdf:
kind: private
port: 9000
health: /status
image: proxy/<org>/hub/vendor/pdfrender@sha256:<64 hex>
user: "10001:10001"
- The app reaches it by its private name, here
http://pdf.<project>.internal:9000(private hostnames). - Your organization must be allowed to deploy images, as for a top-level
image:. Otherwise the upload answers 403external_images_disabled. - The role sets
user: "uid:gid"(not 0) orrun_as: root # reason. Pushleft cannot read a pre-built image’s user before the deploy. - Pushleft does not build or sign this image, and no scan gates it. The image is your responsibility, as with a top-level
image:(registry). In production, a daily scan lists its findings and emails the admins about fixable CRITICAL ones. - While a release that runs it is live, the image keeps a
pl-keep-<deployment>tag, so registry retention does not delete it.
A build per role
A role can build from its own Dockerfile and context. Use this when a repository holds several services.
build: { dockerfile: backend/Dockerfile, context: backend }
roles:
api:
port: 5000
web:
port: 8080
user: "101:101"
build: { dockerfile: frontend/Dockerfile, context: frontend }
- Every role without its own
build:runs the image of the top-levelbuild:. - Pushleft builds all images in one build. If one fails, nothing deploys.
- The same scan gate, SBOM and signature apply to each image.
- The role sets
user: "uid:gid"(not 0) orrun_as: root # reason. - You cannot combine a role’s
build:withimage:. pl up --only webbuilds and rolls one web, private or worker role of the live release. The other roles keep running. The role can have no volumes, and its replica count stays the same.- The daily re-scan lists a role image’s findings and emails the admins about fixable CRITICAL ones. It does not change the deployment’s security status.
Run as a non-root user
Every role runs as a non-root user by default. Set USER in your Dockerfile, or set user: "uid:gid" on the role. A role’s process has no Linux capabilities, so a root process also cannot write files it does not own.
- The effective user. Pushleft uses the role’s
user, or else the image’sUSER. A role without either runs as root. The deployment shows the user of each instance. - Volumes. Before a role starts, Pushleft gives its volumes to the role’s user. Every file in the volume gets that owner, and the deployment records a
volume_owner_alignedevent. Read-only and shared volumes keep their owners. - Exceptions. A role that must run as root declares it, with the reason as a comment:
roles:
proxy:
port: 8080
run_as: root # the vendor image writes /etc at start
- The gate. By default (policy
block), a production build fails withruns_as_rootif a role would run as root withoutrun_as. The error names the role. Previews only show a warning inpl up. Withimage:, Pushleft cannot read the image’s user before the deploy, so each role needs a non-rootuser:orrun_as(build executor).
Routes
Every web role is routed. Its route: sets where you reach it:
hostname: a label (lowercase, at most 20 characters, no--) put in front of the environment hostname:route: { hostname: api }onmain--app--<org>.<base>isapi--main--app--<org>.<base>.path: a prefix such as/apion that hostname. The role gets/apiand everything under/api/. The prefix is not stripped, and the longest prefix wins. Requests that match no prefix go to the role without one on that hostname, or get 404.domains: the verified custom domains of the environment that this role serves, with itspathtoo (pl domain add, wildcards such as*.seller.example.comincluded). A verified domain that no role lists goes to the first web role. Setroute.hostnameon the others when the alphabetical default is wrong.
Without route::
- the first web role by name (alphabetical order, not the order in the file) is on the environment hostname,
- a role that only sets
pathshares that hostname, - any other web role is on
<role name>--<environment hostname>.
To give the first role a label too, set its hostname. A hostname takes each path, and the catch-all, once. pl plan refuses a clash. A deployment whose role hostname would exceed a DNS label (63 characters) is rejected with the reason.
Roles that share a hostname run on the same node, because the ingress of a node reaches only its own containers. Placement puts a role next to the roles it shares a hostname with (also for a replacement), and waits for room there. If sharing roles still end up apart (a volume pinned one elsewhere), the deployment is rejected with that reason. A release is published when every web role is ready, and goes live when all its routes are active.
The same block sets how the ingress proxies to the role. Each field applies to the role’s own requests, also on a hostname it shares under a path:
| Field | Meaning |
|---|---|
max_body | Largest request body, 1MiB to 2GiB. Default 100MiB; larger is refused with 413. |
timeout | Seconds to wait for the role’s response headers, 1 to 3600. Default 60. Slower answers get 502. Streaming responses (server-sent events, WebSockets) pass through after the headers are sent. |
allow_from | [{ path, from }]: requests under path (every path without one) from addresses outside from (CIDRs or addresses, up to 32) get 403. The address is the TCP peer the ingress sees: behind a proxy such as Cloudflare, that is the proxy. |
headers | Response headers set on every answer, up to 16. Hop-by-hop headers, Host, Content-Length and Location cannot be set. |
redirects | [{ path, to, status }]: path (every path without one) answers status (301 default, or 302, 307, 308) with Location: to, a URL or an absolute path. Checked before allow_from. |
min_tls | "1.3": the role’s hostnames, custom domains included, refuse TLS 1.2 handshakes. Default "1.2". On a shared hostname, one role with "1.3" sets it for the whole hostname. Behind a Cloudflare tunnel, Cloudflare terminates TLS: set the minimum in the zone instead. |
roles:
frontend: { kind: web, port: 3000, route: { domains: [market.example.com] } }
backend: { kind: web, port: 8080, route: { path: /api, domains: [market.example.com] } }
admin: { kind: web, port: 8081, route: { hostname: adm } }
Client address
The ingress sets X-Forwarded-For, so your app can rate-limit by client:
- Direct, on a Pushleft hostname or a domain that does not go through a Cloudflare tunnel: the header holds the client’s address only. The ingress drops any
X-Forwarded-Forthe client sends. - Through a Cloudflare tunnel (a linked domain): the header holds the addresses Cloudflare reports, then the tunnel connector’s address (
10.127.255.0/24). - Your container sees the ingress as its socket peer, from the environment network (
10.128.0.0/9).
Trust 10.128.0.0/9 and 10.127.255.0/24 as proxies, and take the rightmost address of X-Forwarded-For that is not one of them. In Rails: config.action_dispatch.trusted_proxies = ActionDispatch::RemoteIp::TRUSTED_PROXIES + [IPAddr.new("10.128.0.0/9"), IPAddr.new("10.127.255.0/24")], then use request.remote_ip.
The tunnel range was 10.127.255.248/29 until 2026-11-13. An app that trusts only that range still sees the client’s address for a node’s first six connectors. Change it to the /24.
Do not trust CF-Connecting-IP, X-Real-IP or Forwarded. The ingress passes them through, so a client can set them on a Pushleft hostname.
Long-lived connections
A WebSocket, or a server-sent events stream, can close at any time. Your client must handle that:
- Configuration changes. When the ingress configuration of a node changes, the WebSockets opened before the change close at most one hour later. The configuration changes when any deployment on that node starts, moves or stops, also another project’s. So a WebSocket closes at most one hour after its route or
allow_fromrule is removed. - Server-sent events are not bounded. A server-sent events stream is an ordinary HTTP response without a connection upgrade. A configuration change does not close it. It stays open until your server ends it or the container stops, even after its route or
allow_fromrule is removed. If access to a stream can be revoked, end the stream from your server after a fixed time (a few minutes). Check access again when the client reconnects. - Deployments. When the role’s container stops (a new release, a move to another node), its streams close.
So your client must reconnect, then get what it missed while it was disconnected. A reconnect alone loses the messages sent in that gap. For example:
- ActionCable (
@rails/actioncable) reconnects and subscribes again by itself. In the subscription’sconnected()callback, fetch the messages after the last one the client has. - Other clients (Socket.IO, a plain
WebSocket, a mobile app): reconnect with a backoff and subscribe again. Then fetch the missed messages with an ordinary HTTP request.
Also fetch again when the app comes back to the foreground. A mobile operating system closes the sockets of an app in the background.
Outbound access
A role reaches the internet by default. Set egress: platform on a role that must not, such as a converter that opens files uploaded by users:
roles:
converter: { kind: worker, command: bin/jobs --queue convert, egress: platform }
The role then reaches only:
- the roles and databases of its environment, also on other nodes;
- HTTPS (TCP 443) to the addresses of Pushleft’s API and object storage. Anything else served over HTTPS on those addresses is reachable too, so treat the rule as “no internet”, not as a list of endpoints;
- the clients of connections made to it, such as a published port.
The agent drops everything else it sends. It applies the rule before the container starts, and the rule survives a reboot. A change of egress is a new release.
Certificates for raw ports
The ingress serves HTTPS for web roles. A role that serves TLS itself, such as IMAP on 993 or SMTP on 465, needs its own certificate. List the hostnames under certificates:
roles:
mail: { kind: private, port: 2993, health: tcp, certificates: [mx.example.com] }
network:
public_ports:
- { port: 993, target_role: mail, target_port: 2993 }
- Each hostname must be in a zone of a ready Cloudflare connection of your organization. A deployment with another hostname is refused.
- Pushleft orders the certificate from Let’s Encrypt. It proves the hostname with a DNS record that it writes through the connection, then deletes the record.
- The role waits until each certificate is issued. The deployment shows
waiting_for_certificatewith the hostname. A first issuance that fails five times fails the role with the reason. - The files are
/run/secrets/certificates/<hostname>/fullchain.pemand/run/secrets/certificates/<hostname>/privkey.pem. The role’s user can read them. Each issuance has a new key, which Pushleft keeps only in Vault. - Pushleft renews a certificate 30 days before it expires, while a deployment used the hostname in the last 30 days. After a renewal, each running instance of a role that lists the hostname restarts with the new files. Expect a short gap per instance.
- A hostname that no deployment uses for 30 days is not renewed, and its certificate expires.
Turnstile
A form that uses Cloudflare Turnstile needs a widget with the hostnames it runs on, and its two keys. Name the secrets that get the keys:
turnstile:
site_key: Turnstile__SiteKey
secret_key: Turnstile__SecretKey
roles:
web: { port: 8080, secrets: [Turnstile__SiteKey, Turnstile__SecretKey] }
- Without a manifest edit: in the console, open Settings, choose the environment under Environment secrets and use Turn on under Turnstile. The API is
GET,PUT {site_key, secret_key, domains?}andDELETE /v1/environments/{id}/turnstile. A widget set in.pl.yamlis changed there: the API refuses to change it. A manifest withturnstiletakes over a widget turned on in the console. - Pushleft creates one managed widget per environment. It uses the Cloudflare connection that links one of the environment’s custom domains. The connection’s token needs Account > Turnstile > Edit.
- A form served on another host, such as a marketing site, needs that hostname in the widget too. List it under
domains:turnstile: { site_key: …, secret_key: …, domains: [example.com, www.example.com] }. In the console, use Other hostnames. - The widget’s domains are the environment’s custom domains. Pushleft updates them within 5 minutes when you add or remove a domain. The keys stay the same. A widget takes at most 10 hostnames, custom domains and
domainstogether: with more, the widget keeps its old domains and the error names the count. - The widget stays in the account where Pushleft created it while that connection exists. If the connection is removed, Pushleft creates a new widget and restarts the running instances that list its secrets, one short gap each.
- Pushleft writes the site key and the secret key as the two environment secrets. List them under a role’s
secretsas usual.pl secrets listshows them. - The roles wait until the keys are written. The deployment shows
waiting_for_turnstile. A first widget that fails five times fails the roles with Cloudflare’s reason. - When a deployment without
turnstileis live, Pushleft deletes the widget. If that deployment fails, the live release keeps the widget. Pushleft also deletes the widget of an environment that has no active deployment for a day. The two secrets stay until a new widget replaces them.
Published ports
Web traffic reaches a role through the ingress (80/443). A role that must take raw TCP or UDP from the internet, such as a mail server or a TURN relay, declares it under network.public_ports:
network:
public_ports:
- { port: 25, target_role: mx, target_port: 2525, address: 203.0.113.7 }
- { port: 587, target_role: mx, target_port: 2587, address: 203.0.113.7 }
- { port: 3478, protocol: udp, target_role: turn, target_port: 3478 }
- { port: 49152, port_end: 49200, protocol: udp, target_role: turn }
roles:
mx: { kind: private, port: 2525, health: tcp }
turn: { kind: worker }
A role with a port gets an HTTP health probe (health, default /healthz), which an SMTP or TURN server fails. A target that does not speak HTTP sets health: tcp, so a TCP connect to its port is the probe. A worker without port is checked by process liveness. target_port names the container port either way.
- Target. A web, private or worker role of the manifest with one replica: the port is forwarded to that one container.
target_portis the container’s port. A range (port_end, at most 256 ports) keeps its numbers, so it takes notarget_portor the same one. - Address. Without
address, the port is on the main public IPv4 of the role’s node.addressnames an extra IPv4 that an operator assigned to the organization on a node (pushleft-controller fleet address-add). The role then runs on that node, and its own outbound connections leave from that address too, so a mail server’s PTR matches. - Claims. A port on an address belongs to one environment while its release is live. The first claim wins, and a later environment’s forward of the same port is not set up. Ports 22, 80 and 443 are the host’s.
- Production only. Previews never publish ports.
- Source.
source_cidrslimits a port to public source ranges. - Firewall. On a Robot host, the operator also opens the port in the Robot firewall (robot hosts).
The agent builds the forwards in its own nftables table per environment (plp_<environment>). It uses DNAT on the public interface to the container, and SNAT for a role with its own address. Docker publishes nothing.
Projects
The first deployment that names a new project creates it. POST /v1/projects {"slug"} (members and up) creates one before that. Every project has an immutable id of 8 or more hex characters. A slug cannot look like an id, so a name is always either a slug or an id. An unknown id is refused, and no project is created. GET /v1/environments gives each environment’s project_id too. GET /v1/projects lists each project with its id, slug, environments and hostname_label.
The label goes into the project’s URLs (<label>--<handle>, <branch>--<label>--<handle>). Pushleft fixes it when the project is created: the slug, or <slug>-<id> when another project of the organization already uses that label. PATCH /v1/projects/{id} {"slug"} (admins) renames a project. Its URLs do not change. After a rename, set the new slug or the id in .pl.yaml, because the old slug would create a new project. DELETE /v1/projects/{id} (admins) deletes a project.
The CLI has the same operations. A project is named by its slug or its id:
pl project list # id, slug and environments of each project
pl project create shop
pl project rename shop shop-old # admins
pl project delete shop-old --yes # admins
Pushleft deletes a project only when nothing of it runs or keeps data. Until then, the request is refused with a list of what is left and the command that removes each item:
- a deployment that is not destroyed, failed, superseded or cancelled:
pl down <deployment> - a database that is not destroyed:
pl db delete <database> --yes(afterpl down) - a volume that is not released: it is released when its deployment is torn down
- a bucket:
pl storage bucket delete <id> - a custom domain:
pl domain remove <id> - a secret:
pl secrets rm <name> --project <slug> --environment <environment> - an AI token, mail token or error DSN that still works:
pl ai token revoke,pl mail token revoke,pl errors dsn revoke - an AI provider key:
DELETE /v1/ai/keys/<id> - the environment network: Pushleft tears it down after the last deployment and database are gone
The deployment history stays for 7 days after the deletion. Then Pushleft removes it: deployments, events, jobs, sources, releases, destroyed databases, the network, logs and other history of its environments (retention). Billing records, the audit event and backups stay for their own retention. A deleted project is no longer in lists, and its slug and id no longer resolve, so nothing can be deployed to it. Its slug is free for a new project. Its hostname label stays reserved, so a new project with the same slug gets <slug>-<id> URLs and never the old ones. You cannot undo a deletion.
A project can have an icon. The console shows it in the project picker and on the overview. PUT /v1/projects/{id}/icon (admins) takes the image as the request body: PNG, JPEG, WebP or ICO, at most 256 KiB. The API checks the bytes of the file and ignores its declared type. It refuses SVG. GET /v1/projects/{id}/icon returns the image. DELETE /v1/projects/{id}/icon removes it. GET /v1/projects gives icon_version, a hash of the image, or null. Without an icon, the console uses the live app’s favicon, or else the project’s initials.
Secrets
A secret belongs to one environment of one project. Set it before or after the first deployment:
printf '%s' "$STRIPE_KEY" | pl secrets set STRIPE_KEY # this checkout's preview/<branch>
pl secrets set STRIPE_KEY --production < stripe.key # production
pl secrets list # names and versions only
pl secrets rm STRIPE_KEY
pl secrets set creates the environment if it does not exist. The API (PUT /v1/environments/{id}/secrets/{name}, GET /v1/environments/{id}/secrets, DELETE …/{name}, POST /v1/environments, GET /v1/environments) and the console’s Settings page do the same. Names match [A-Za-z_][A-Za-z0-9_]{0,63} and do not start with PUSHLEFT_; values are 1 byte to 64 KiB.
Storage. The value is stored only in Vault, at organizations/<org>/environments/<env>/secrets/<name>. The API’s Vault policy can create, update and delete these paths. It cannot read them. PostgreSQL holds the name, a version counter and who changed it. No API, CLI command or console page returns a value.
Delivery. When a role’s container starts, the agent gateway reads the role’s secrets as single-use wrapping tokens, only under the lease’s own organization and environment. It puts them in that lease. The node unwraps each one once.
NAMEor{ name: NAME, as: file }(the default): the file/run/secrets/NAME, in a read-only mount. The files are 0444 and owned by the container’s root, so every user in the container can read them, as with Docker secrets. They are not in the container’s configuration.{ name: NAME, path: /etc/app/app.conf }: the same file, also bound read-only at that path, for an image that reads its configuration from a fixed place (rspamd’slocal.d,nats.conf). The path is absolute and normalized, outside/proc,/sys,/dev,/run/secretsand the role’s volumes and tmpfs mounts, and used by one secret only. A configuration file that is not secret is stored the same way (pl secrets set).{ name: NAME, as: env }: the variableNAME, through a 0600--env-filethat the agent deletes as soon as Docker has created the container. Docker keeps environment variables in the container’s configuration, so root on that host can read them withdocker inspect. Use files when the application can read them. A value with a line break cannot be a variable.
A missing secret fails the release permanently and names the secret. A changed value reaches containers that start after the change: the next deployment, or a replacement instance.
Configuration sets
A configuration set is a named set of plain variables that belongs to a project. You assign it to an environment. Use one for each value that differs between environments, such as a public URL or the id of a test shop. Then production, staging and previews each keep their own values, and a change for one of them cannot reach another.
pl config set staging PUBLIC_URL=https://staging.example.com SHOP_ID=582 # create the set, or change it
pl config assign staging --environment staging # one environment
pl config assign production --production
pl config assign previews --previews # each preview without a set of its own
pl config list # sets, variables, environments
pl config unset staging SHOP_ID
pl config unassign --environment staging
pl config rm staging # only a set that is assigned nowhere
pl config assign without a target assigns the set to this checkout’s preview/<branch>. It creates the environment if it does not exist.
Precedence. For the same name, the highest of these wins:
- the environment’s configuration set
- a role’s
env - the top-level
env
A preview takes its own set first, then the set assigned with --previews. Production never takes the preview set. An environment without a set runs with .pl.yaml alone.
When a change applies. Pushleft reads the set when you deploy. A change to a set or to an assignment reaches an environment at its next pl up, as a new release. Nothing redeploys by itself. The deployment’s event log names the set.
Rules. A set name is 1 to 63 lowercase letters, digits and dashes. The variables follow the rules of env: at most 128, with no PORT and no PUSHLEFT_ names. A deployment refuses a set variable with the name of a secret delivered as: env, or of a variable that a database injects.
Secrets. A set holds plain values, and pl config list prints them. A secret already belongs to one environment, so it needs no set.
Access. Members of the project change sets and assign them. Production needs an admin: to assign a set to it, and to change a set that it runs with. The API is GET /v1/projects/{project}/configuration-sets, PUT and DELETE …/configuration-sets/{name}, and POST /v1/projects/{project}/configuration-assignments.
To move a project to sets, put each variable that belongs to one environment in that environment’s set, and remove it from .pl.yaml. Keep the variables that are the same everywhere in .pl.yaml.
Databases
Declare logical databases under the engine. Pushleft creates them with the instance (managed databases):
data:
postgres:
plan: starter
databases: [{ name: app, extensions: [vector] }, { name: audit, owner_login: audit_app }]
clickhouse:
databases: [{ name: events }]
valkey:
plan: dev
eviction: noeviction # maxmemory-policy; the default never drops keys
databases: [{ name: jobs }]
disk: 300GiBoptionally sets the initial persistent allocation, separately from the plan’s CPU and memory. Use wholeGiBorTiB, up to1TiB, and at least the plan’s default disk. PostgreSQL plan floors are 10/20/50/100/100/200 GiB (dev/starter/standard/performance/large/xlarge), and ClickHouse floors are 20/50/100/250 GiB (dev/starter/standard/performance). The scheduler reserves that capacity, and the agent enforces the same XFS project quota. After a host allocation exists, a change to the custom disk, or its removal, is refused. Use a new environment for another size. This sets the initial size only and does not resize online. Restore, relocation and upgrade generations keep the configured size.- Names and logins are
[a-z_][a-z0-9_]{0,62}, unique across engines and at most 16 per engine. They cannot be engine or Pushleft reserved names.owner_logindefaults to the database name. - PostgreSQL: the database is owned by the NOLOGIN role
<name>_owner. The login getsconnect,read,writeandmigrate(it runs as the owner role in that database, so it can create schemas and tables). ClickHouse: the login gets the same grants, with table engines limited to the local ones. extensions(PostgreSQL only): extensions Pushleft creates in that database, in schemapublic, before any role that uses it starts. Allowed: the list in extensions, among themvector(pgvector),pg_textsearch,postgis,pg_trgmandbtree_gin. Your login is not a superuser and cannot createvectoritself; your migrations’CREATE EXTENSION IF NOT EXISTS vectorthen finds it and does nothing. You can add an extension in a later deployment. Removing one from the manifest drops nothing (extensions).- The login’s password is 256 random bits. The agent gateway creates it once in Vault (
…/databases/<engine>/logins/<login>, create-only). Nobody sets or sees it. When you remove a database from the manifest, Pushleft deletes nothing (deleting a database). - Valkey has one keyspace per instance: each entry under
databasesis a login (an ACL user) with access to every key and channel. Its rights follow the grants: Lua scripts, MULTI and blocking pops for writers, pub/sub, never admin commands,FLUSHALLorMIGRATE.evictionis one ofnoeviction(the default, for job queues such as Hangfire),allkeys-lru,allkeys-lfu,allkeys-random,volatile-lru,volatile-lfu,volatile-randomorvolatile-ttl. Plans:dev0.25 CPU / 256 MiB / 2 GiB,starter0.5 / 1 GiB / 5 GiB,standard1 / 2 GiB / 10 GiB,performance2 / 4 GiB / 20 GiB.maxmemoryis 75% of the memory. - The database container has a fixed address on its host’s environment network: x.126 for PostgreSQL, x.125 for ClickHouse, x.124 for Valkey. Roles on other hosts reach it over the environment mesh. It publishes no port.
- A role that lists a database, release roles included, starts only when the instance, the database and its login are ready. If a database or login fails, the deployment fails.
- To reach a database from your machine, use
pl db connect(developer access).
A role that lists databases gets, through the same path as as: env secrets:
| Engine | Variables |
|---|---|
| PostgreSQL | PUSHLEFT_DATABASE_<NAME>_URL (postgres://login:password@host:5432/name) for each. When the role uses exactly one PostgreSQL database, also DATABASE_URL, PGHOST, PGPORT, PGDATABASE, PGUSER and PGPASSWORD. |
| ClickHouse | PUSHLEFT_CLICKHOUSE_<NAME>_URL (http://login:password@host:8123/?database=name), _HOST, _DATABASE, _USER, _PASSWORD. The native port is 9000. |
| Valkey | PUSHLEFT_VALKEY_<NAME>_URL (redis://login:password@host:6379/0), _HOST, _USER, _PASSWORD. When the role uses exactly one Valkey login, also REDIS_URL and VALKEY_URL. |
<NAME> is the database name in upper case. You cannot also set these names in env. If your application wants its own variable names, compose them in a shell-form command, for example command: ConnectionStrings__Postgres="Host=$PGHOST;Database=$PGDATABASE;Username=$PGUSER;Password=$PGPASSWORD" exec dotnet App.dll.
From Docker Compose
pl compose convert writes a .pl.yaml from a Compose file. Pushleft does not run Compose files themselves.
pl compose convert # compose.yaml or docker-compose.yml here: prints the manifest
pl compose convert docker-compose.yml --project shop --write
The command lists every setting it could not carry over, by service and name. Read that list before pl up.
| Compose | .pl.yaml |
|---|---|
A service on a postgres, clickhouse, redis or valkey image | A managed database under data:. Variables that point at it are dropped, because Pushleft injects the connection. |
build | The first becomes the top-level build:, and other ones become a role build:. |
image of any other service | Listed: push it to your registry and pin it by digest. |
ports, expose | port: (the container side). The first service with published ports is web, the others private. Without a port the role is a worker. |
command, entrypoint | command: (a string stays shell form, a list exec form). |
environment | env:. Names with PASSWORD, SECRET, TOKEN or a key in them become secrets:. Set those with pl secrets set first. |
Named volumes | Role volumes: of 1 GiB; shared: true when several services write one. Bind mounts are listed. |
healthcheck against localhost | health: with its path. |
deploy.replicas, deploy.resources.limits | replicas: and resources:, rounded up to the allowed sizes. |
tmpfs, numeric user | tmpfs: (64 MiB each) and user:. |
${NAME:-default} takes its default. Any other interpolation, env_file, networks and depends_on on a service that is not a database are listed.
Unsupported
- Per-role
build. A role’s own image comes from the registry (a second image). - A database or role shared between environments or projects.
- Object storage in the manifest. Create buckets with
pl storage bucket create(object storage). - Extensions outside the list in
extensions. Trusted extensions that the image ships can still be created by your migrations. - More than one
pathper route, and extra database logins (read-only or with a password you set).
Related
- Managed databases: what runs behind
data:. - Domain registration and DNS: claim and verify the domains in
route.domains. - Registry: deploy an image with
image:. - Object storage: buckets and their secrets.
- Authentication: sign in before
pl up.
Preview region
Without preview.region, previews run in the regions of your organization’s own nodes, or in fsn1 when it has none. The organization’s work placement setting decides between its nodes and Pushleft’s. To pin a region, name it:
preview:
region: lab1
The roles, the databases and the build go to nodes in that region. A region without a build node of your organization builds in a region that has one. Production regions stay under production.regions.
A preview does not move when you change the region. Its database stays on its node, so the deployment waits for capacity. To move a preview:
- Tear it down:
pl down <deployment>. Wait untilpl listshows itdestroyed. - Delete each of its databases:
pl db delete <database> --yes(pl db listgives the IDs). Take a checkpoint first if you need the data. - Wait until
pl db listshows none of them asdestroying. - Set
preview.regionand runpl up.
The URL stays the same. A node without a public address serves traffic only when it was enrolled with --tunnel (nodes behind NAT).