pushleft
Deploy your first app
Agent skill

Let your agent deploy it.

Copy one file into your repository. Your coding agent then installs pl, writes .pl.yaml, makes the Dockerfile non-root and deploys a preview. It asks you before production.

In Claude Code, ask it to deploy to Pushleft or run /pushleft. Other agents read the same file as instructions.

Install in this repository
mkdir -p .claude/skills/pushleft && curl -fsSL https://pushleft.dev/skill.md -o .claude/skills/pushleft/SKILL.md
The skill
---
name: pushleft
description: Set up and deploy a project on Pushleft end to end. Installs and checks the pl CLI, reads the checkout, writes a .pl.yaml (roles, routes, databases, secrets, volumes, cron, outbound access), makes the Dockerfile run as a non-root user, sets secrets, buckets and mail, deploys a preview and then production, and fixes common deploy failures. Use when the user says "deploy this to Pushleft", "set up Pushleft", "write a .pl.yaml", "pl up fails", "make my Dockerfile non-root", or invokes /pushleft.
---

# Pushleft deployment

You take a checkout to a live Pushleft URL. You install `pl`, write one `.pl.yaml` at the root and make the image run as a non-root user. Then you set the secrets and deploy a preview, and production when the user agrees. The manual is the source of truth. When a rule here and the manual differ, the manual wins:

- Manifest: https://pushleft.dev/manual/manifest/
- Non-root rule and the build gate: https://pushleft.dev/manual/build-executor/#effective-user
- The whole manual as one file: https://pushleft.dev/llms-full.txt
- Setups that run today, with their `.pl.yaml`: https://pushleft.dev/recipes/

## Rules for you

- Never print, log or commit a token or a secret value. Pipe values into `pl secrets set`; never put them on a command line or in a file in the repository.
- Use `pl` for every Pushleft action. Do not call the API by hand when a command exists.
- Deploy a preview when the user asks you to deploy. Ask before `pl up --production`, `pl down`, `pl db delete` and any command with `--yes`.
- Do not invent fields or flags. `pl <command> --help` and the manual list them.

## What Pushleft does to every container

Know these before you change anything. They decide what the Dockerfile may do.

- Every Linux capability is dropped and `no-new-privileges` is set. A process cannot switch users, bind a port below 1024, or `chown`. Root in the container cannot write files it does not own.
- The root filesystem is read-only. Writable paths are `/tmp` (64 MiB tmpfs), declared `tmpfs` mounts and declared `volumes`.
- Each role runs as its `user:` from `.pl.yaml`, or else as the image's `USER`. With neither, it runs as root.
- Before a role starts, Pushleft gives its writable volumes to the role's uid:gid. You never chown a volume yourself.
- In production, a role that would run as root fails the build with `runs_as_root`, unless the role has `run_as: root  # reason`. Previews only warn.

## Workflow

### 0. Install and sign in

1. Check for the CLI: `pl --version`. On macOS, `/usr/bin/pl` is Apple's plist tool, not Pushleft's.
2. If it is missing, install the signed release for the platform (`pl-darwin-arm64` or `pl-linux-amd64`) from https://pushleft.dev/manual/fleet/#signed-pl-releases. Check the signature and the checksum as that page shows. There is no self-update.
3. Check the sign-in: `pl whoami`. If it fails, ask the user to sign in to the console with **Email me a link**, then run `pl login --email <their email> --code <code from the mail>` themselves. Do not ask for the code in the chat.
4. `pl org list` shows the stored logins. Use `--org <name>` on each command when the project is not in the default organization.

### 1. Read the checkout

Find out, from files and not from guesses:

- the language, framework and package manager;
- every long-running process: web server, background worker, scheduler, queue consumer (Procfile, `compose.yaml`, `package.json` scripts, `bin/`, systemd units, the README);
- the port each one listens on, and its health path (`/healthz`, `/up`, `/health`). A web role needs a health path that answers 200 without a login;
- one-off commands: migrations (a `release` role), cron jobs (a `cron` role);
- databases and caches it connects to (PostgreSQL, ClickHouse, Valkey/Redis), and the variable names the code reads for them;
- secrets: every variable that holds a key, password or token. Note their names only, never their values;
- paths it writes at run time: uploads, caches, SQLite files, generated assets, PID files;
- any existing `Dockerfile`, `.dockerignore` and `.pl.yaml`.

Tell the user in a few lines what you found before you write anything.

### 2. Write `.pl.yaml`

Start from the smallest manifest that works, then add only what step 1 found.

```yaml
version: 1
project: shop                     # DNS-safe slug, no "--"
roles:
  web:
    kind: web
    port: 8080                    # 1024 or higher
    health: /healthz
    secrets: [STRIPE_KEY]         # names only; values go in with pl secrets set
    databases: [shop]
    volumes: [{ name: uploads, size: 5GiB, mount: /app/uploads }]
  worker:
    kind: worker
    command: bin/jobs
    databases: [shop]
  release:
    kind: release                 # runs once per deploy, before web starts
    command: bin/rails db:migrate
    databases: [shop]
data:
  postgres:
    plan: starter
    databases: [{ name: shop }]
```

Rules:

- Ports are 1024 or higher. If the app listens on 80 or 443, change its port (or its `PORT` variable); Pushleft sets `PORT` for every role with a port.
- A path the app writes at run time is a `volume` when it must survive a deploy, and a `tmpfs` when it is scratch. Everything else is read-only.
- A volume needs `name`, `mount` and, on the role that writes it, `size` (`1GiB` to `1TiB`). Only one role writes a volume, with one replica. Only `web`, `private` and `worker` roles mount volumes. If you have to guess the size, say so in the hand-over.
- Databases come from `data:`. The role gets `DATABASE_URL` and the `PG*` variables. Map other variable names in the app, not in the manifest.
- Secrets arrive as files under `/run/secrets/NAME`. Use `{ name: NAME, as: env }` when the app only reads environment variables.
- Web roles are routed. The first web role by name gets the environment hostname. Give the others `route: { hostname: <label> }`, or `route: { hostname: <shared label>, path: /api }` to share one hostname. Roles that share a hostname run on one node.
- A WebSocket or server-sent events endpoint is a `web` role. It needs no other setting.
- A background job runner is a `worker` with its `command`. A periodic task is `kind: cron` with `cron: { schedule: "*/5 * * * *" }` (UTC).
- A role that opens files from users, or that must not reach the internet, gets `egress: platform`. It still reaches its databases, its other roles and Pushleft's storage and mail.
- Object storage is not in the manifest. Create a bucket in step 6, and list its five secrets on the roles that use it.
- Production needs `production: { regions: [fsn1] }`. Previews run in `fsn1`, or on the organization's own servers when it has them (`preview: { region: <region> }`).
- If the repository has a Compose file, start from `pl compose convert` and read the list of what it could not carry over.
- Do not add fields you are not sure of. The parser refuses unknown fields; check the manifest page.

### 3. Make the Dockerfile non-root

Every role must run as a non-root user. Prefer a numeric `USER uid:gid` in the final stage, so the check does not depend on the image's `/etc/passwd`.

Steps for the final stage:

1. Create the user, or use the one the base image ships (see the table).
2. Copy application files with `--chown=<uid>:<gid>`, or leave them root-owned and read-only. The app must not need to write them.
3. Create every directory the app writes, owned by the user (`RUN mkdir -p /app/uploads && chown 10001:10001 /app/uploads`). In Pushleft these paths are `tmpfs` or `volumes`, and Pushleft gives a volume to the role's user before it starts. Plain `docker run` without `--read-only` then works too.
4. Listen on a port of 1024 or higher.
5. End with `USER <uid>:<gid>`. Nothing after it may need root.

| Base image | Non-root user |
|---|---|
| `node` | `USER node` (1000:1000) is built in. Use `USER 1000:1000`. |
| `python`, `debian`, `ubuntu` | `RUN groupadd -g 10001 app && useradd -u 10001 -g app -M -s /usr/sbin/nologin app`, then `USER 10001:10001`. |
| `alpine` | `RUN addgroup -g 10001 app && adduser -u 10001 -G app -D -H app`, then `USER 10001:10001`. |
| `ruby` (Rails 7.1+ Dockerfile) | The generated Dockerfile already has `USER 1000:1000` (`rails`). Keep it. |
| `mcr.microsoft.com/dotnet/aspnet` 8+ | `USER $APP_UID` (1654) is built in. Use `USER 1654:1654`, and set `ASPNETCORE_HTTP_PORTS=8080`. |
| `golang` build, `distroless` or `scratch` final | `gcr.io/distroless/static:nonroot` runs as 65532. With `scratch`, add `USER 65532:65532`. |
| `nginx` | Use `nginxinc/nginx-unprivileged` (101:101, port 8080), or keep `nginx` and set `user: "101:101"` on the role with `listen 8080;` and the pid and temp paths under `/tmp`. |
| A vendor image you cannot rebuild | A role with its own `image:` (see "A second image" below), and `user: "uid:gid"` on that role instead of changing the image. |

Do not use `sudo`, `gosu`, `su-exec` or an entrypoint that starts as root and drops privileges. Without capabilities, the switch fails at start. Remove such an entrypoint; a `chown` it did for a volume is no longer needed.

Add a `.dockerignore` if there is none, so the build context and the image stay small: at least `.git`, and the dependency and build folders the Dockerfile installs or builds itself (`node_modules`, `target`, `.venv`, `tmp`, `log`).

### A second image

A part that runs from another image (a vendor service you cannot rebuild, a search engine) is a role with its own `image:`, in the same `.pl.yaml` and the same environment. The app reaches it by its private name, `http://<role>.<project>.internal:<port>`.

```yaml
  pdf:
    kind: private
    port: 9000
    health: /status
    image: proxy/<org-uuid>/hub/vendor/pdfrender@sha256:<64 hex>
    user: "10001:10001"          # or run_as: root  # reason
```

- The image must be in the organization's Pushleft registry namespaces, pinned by digest: `organizations/<org-uuid>/<repo>@sha256:...` (pushed there) or `proxy/<org-uuid>/<upstream>/<path>@sha256:...` (pulled through). Ask the user for the digest; never invent one.
- The organization must be allowed to deploy images. New organizations are not; an operator turns it on.
- The role needs `user: "uid:gid"` (not 0) or `run_as: root  # reason`: Pushleft cannot read a pre-built image's user. Pick a uid the image can run as; ask when you cannot tell.
- Pushleft does not build or sign that image, and no scan gates it. In production a daily scan only reports its findings. Tell the user that keeping it patched is their responsibility.
- Its writable paths still need `tmpfs` or `volumes`, like any role.
- If the user owns the code of that part, prefer building it from this checkout (a second build stage and a `command`) over a separate image.

### 4. When something seems to need root

Before you accept root, try the non-root fix: a higher port, a writable path moved to `/tmp` or a volume, a file chowned at build time, an unprivileged variant of the image, `user:` on the role. Ask the user even when the project already says root is required, and put the concrete non-root fix in the first option, so they can choose it. In Claude Code, use AskUserQuestion with these options, the first one marked recommended:

- **Make it non-root (recommended).** Explain the change you would make and why it is safe.
- **Must run as root.** The role keeps root, and you add `run_as: root  # <reason>` to that role. Ask for the reason in one sentence. It is required, at most 200 characters, and shown on every deployment.
- **Root for now, fix later.** Same `run_as` line, with a reason that says so. Warn that a production deploy of a role without `run_as` fails.

Never add `run_as: root` without the user's answer. Never write a reason the user did not give or confirm.

```yaml
roles:
  legacy:
    port: 8080
    run_as: root  # vendor image writes /etc/app at start; tracked in ISSUE-142
```

`run_as` takes only `root`, and it cannot be combined with a non-root `user:`.

Root does not make a path writable. The root filesystem is still read-only and root still has no capabilities, so a path the process writes needs a `tmpfs` or a `volume` either way.

If `pl plan` says `unknown field 'run_as'` or `'image'` on a role, the user's `pl` is older than 2026-11-07. Do not drop the line. Tell them to install `pl` 0.1.0-ae5a298 or later (it also accepts a role's `image:`), following https://pushleft.dev/manual/fleet/#signed-pl-releases (download, signature and checksum check; there is no self-update). A CI job that pins an older `pl` version needs the same bump.

### 5. Check it

Run what is available, and report what you could not run:

```sh
pl plan                                             # validates .pl.yaml, works without login
docker build -t app-check .
docker run --rm --entrypoint id app-check           # uid must not be 0
```

If the image has no `id` binary (distroless), check `docker image inspect --format '{{.Config.User}}' app-check` instead.

Then start each long-running role the way Pushleft does: read-only root, no capabilities, `/tmp` as tmpfs, and each of the role's volumes and `tmpfs` paths mounted. For the web role:

```sh
docker volume create app-check-uploads             # one per volume of the role
# Pushleft gives a volume to the role's user before it starts; do the same here.
docker run --rm -v app-check-uploads:/v alpine chown -R 10001:10001 /v
docker run -d --name app-check --read-only --cap-drop ALL \
  --security-opt no-new-privileges --tmpfs /tmp \
  -v app-check-uploads:/app/uploads \
  -e PORT=8080 -p 127.0.0.1:18080:8080 app-check
sleep 3 && curl -fsS http://127.0.0.1:18080/healthz  # the role's health path
docker logs app-check
```

Use the uid:gid of the image's `USER` (or the role's `user:`) in that `chown`. Exercise one write to each volume if the app has an easy way to do it. Start each `worker` with its `command` the same way (a string `command` runs as `/bin/sh -c "<command>"`, a list runs as is) and check that it is still running after a few seconds. Run each `release` command once and check that it exits 0. Use a free host port if 18080 is taken.

Clean up afterwards: `docker rm -f app-check`, `docker volume rm app-check-uploads`, `docker rmi app-check`.

### 6. Secrets, storage and mail

Each environment has its own secrets: a preview (`preview/<branch>`) and production. Set them for the preview first, and for production with `--production` before the first production deploy.

```sh
pl secrets set STRIPE_KEY < stripe.key                  # the user's file; never echo the value
pl secrets list                                         # names and versions only
pl storage bucket create files --set-secret             # S3_ENDPOINT, S3_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
pl mail domain add example.com                          # prints DNS records for the user to publish
pl mail domain verify example.com --wait 120
pl mail token create app | pl secrets set MAIL_TOKEN    # list it as { name: MAIL_TOKEN, as: env }
```

Ask the user for each secret value, or ask them to run the command. A missing secret fails the release and names it.

### 7. Deploy

1. `pl plan` until it prints the resolved manifest with no error.
2. `pl up` deploys a preview of this branch and follows it to the URL.
3. Open the URL and check the health path. `pl logs` shows the service output (`--role <name>`, `-f`). `pl exec <role> -- <command>` runs a command in a role.
4. Ask the user before production. Then set the production secrets and run `pl up --production`.
5. A custom domain: `pl domain add shop.example.com --production`, then the user creates the DNS record it prints. List it under the role's `route: { domains: [...] }`.

Other commands the user may need:

- `pl list`: the deployments.
- `pl db connect`: a database from this machine.
- `pl schedules run <name>`: start a scheduled job now.
- `pl nodes enroll --pool application --region <region>`: add their own server. Add `--tunnel` when it has no public address.
- `pl nodes placement`: where new work runs, their servers or Pushleft's.

### When a deploy fails

| Message | Do this |
|---|---|
| `unknown field` from `pl plan` | Remove or fix the field. If the manual has it, the user's `pl` is too old: install the current release. |
| `runs_as_root` | Step 3, or ask the user and add `run_as: root  # reason`. |
| `image_scan_blocked` (production only) | Update the base image or the packages it names, and deploy again. Only if the user insists: an admin runs `pl security waive --reason "<why>" --hours 24`. |
| `waiting_for_capacity` | The event names the resource that does not fit. Make `resources` smaller, or ask the user to add a server or change `pl nodes placement`. Pushleft cancels the deployment after 10 minutes of waiting. |
| A role fails its health check | Read `pl logs --role <name>`. Check that it listens on `$PORT` on `0.0.0.0` and that the health path answers 200 without a login. Raise `startup_timeout` (10 to 600) for a slow start. |
| A missing secret | Set it for that environment with `pl secrets set`, then deploy again. |

### 8. Hand over

Tell the user, in a short list:

- the files you created or changed;
- each role, its port, its user and its URL;
- any role with `run_as: root` and its reason, and any role with `egress: platform`;
- the secrets still to set, as commands with no values;
- what is live (preview, production) and the next step.

Start from a recipe.

The agent picks the closest recipe and checks the result with pl plan.

See the recipes → Read the manual page →