pushleft
Deploy your first app
Recipes

Start from a setup that runs.

Each recipe is a setup that runs on Pushleft today, with its network and its .pl.yaml. Drag to turn the model. Point at a server to see what runs on it, and click it to open its manual page.

Blue boxes are our servers. White boxes are your servers. Grey boxes are outside Pushleft.

Drag to orbit · click a server
Servers in this recipe

    Web app and database

    Most apps start here, with one PostgreSQL database.

    The release role runs your migrations before the new web role takes traffic.

    Everything runs on our servers in fsn1.

    .pl.yaml
    project: shop
    roles:
      web: { port: 8080, databases: [app] }
      release: { command: bin/migrate, databases: [app] }
    data:
      postgres: { plan: starter, databases: [{ name: app }] }
    production:
      regions: [fsn1]

    Front end and API on one hostname

    The browser calls the API on its own origin, so you need no CORS.

    Requests under /api go to the server role. All other requests go to the app role.

    Roles that share a hostname run on the same node.

    .pl.yaml
    project: store
    roles:
      # app is first by name, so it takes the hostname; server shares it under /api.
      app: { kind: web, port: 8080, user: "101:101" }
      server: { kind: web, port: 5000, route: { path: /api }, databases: [app] }
    data:
      postgres: { plan: starter, databases: [{ name: app }] }
    production:
      regions: [fsn1]

    API, WebSockets and a worker without internet

    Use this when one codebase runs as several roles, and one of them handles files you do not trust.

    With egress: platform, that worker reaches its databases, its other roles and the HTTPS addresses of Pushleft, object storage included.

    Pushleft drops all other traffic it sends.

    The WebSocket role is a web role on its own hostname.

    .pl.yaml
    project: decks
    roles:
      api: { kind: web, port: 3000, databases: [app] }
      cable: { kind: web, port: 3001, route: { hostname: ws }, databases: [app] }
      worker: { kind: worker, command: bin/jobs, databases: [app] }
      converter:
        kind: worker
        command: bin/jobs --queue convert
        databases: [app]
        egress: platform
    secrets:
      - { name: S3_ENDPOINT, as: env }
      - { name: S3_BUCKET, as: env }
      - { name: AWS_REGION, as: env }
      - { name: AWS_ACCESS_KEY_ID, as: env }
      - { name: AWS_SECRET_ACCESS_KEY, as: env }
    data:
      postgres: { plan: starter, databases: [{ name: app }] }
    production:
      regions: [fsn1]
    Commands
    # first deploy without the secrets: block, so the environment exists
    pl up --production
    # the bucket and its five secrets
    pl storage bucket create files --production --set-secret
    # add the secrets: block back, then deploy again
    pl up --production

    Two front ends on their own domains

    One repository holds an API and two static front ends.

    Each front end has its own Dockerfile, its own hostname and its custom domain.

    One build makes all three images, so the three always deploy together.

    .pl.yaml
    project: studio
    build: { dockerfile: api/Dockerfile, context: api }
    roles:
      api: { kind: web, port: 3000, route: { hostname: api } }
      app:
        kind: web
        port: 8080
        user: "101:101"
        build: { dockerfile: app/Dockerfile, context: app }
        route: { domains: [app.example.com] }
      viewer:
        kind: web
        port: 8080
        user: "101:101"
        build: { dockerfile: viewer/Dockerfile, context: viewer }
        route: { hostname: view, domains: [view.example.com] }
    production:
      regions: [fsn1]
    Commands
    # first deploy, so the production environment exists
    pl up --production
    # claim each domain; each prints the DNS records to publish
    pl domain add app.example.com --production
    pl domain add view.example.com --production
    # publish them at your DNS host, then wait for active
    pl domain list

    Your own servers behind NAT

    Use this when your servers have no public address, for example in an office or a lab.

    Traffic reaches them through a Cloudflare tunnel, so you open no inbound port.

    With own_only placement, no work goes to our servers, and compute costs nothing.

    .pl.yaml
    project: portal
    roles:
      web: { port: 8080, databases: [app] }
    data:
      postgres: { plan: starter, databases: [{ name: app }] }
    production:
      regions: [lab1]
    preview:
      region: lab1
    Commands
    pl nodes enroll --pool application,database --region lab1 --tunnel
    pl nodes placement --production own_only --preview own_only

    Previews on your servers, production on ours

    Previews sometimes need something only your site has, such as an API key that accepts only your office address.

    Previews run on your servers in lab1. Production runs on our servers in fsn1.

    Placement is set per environment kind, in the console or with pl nodes placement.

    .pl.yaml
    project: search
    roles:
      web: { port: 8080, databases: [app] }
      engine: { kind: private, port: 8421 }
    data:
      postgres: { plan: starter, databases: [{ name: app }] }
    production:
      regions: [fsn1]
    preview:
      region: lab1
    Commands
    pl nodes placement --production pushleft --preview own_only

    Scheduled tasks on an office server

    Some tasks must run next to a system on your site, behind your firewall.

    The server needs only outbound HTTPS to Pushleft. It needs no inbound port.

    A cron role never starts a second run while one is active.

    .pl.yaml
    project: sync
    roles:
      orders:
        kind: cron
        cron: { schedule: "*/5 * * * *" }
        command: bin/sync-orders
        secrets: [ERP_TOKEN]
    production:
      regions: [office1]
    Commands
    pl nodes enroll --pool application --region office1

    Nightly test run in a throwaway VM

    A test suite that needs Docker and runs for hours fits here.

    Each run gets a fresh VM, and Pushleft destroys it when the run ends. The cache volume stays.

    Pushleft sends mail only when the script fails. On your own workspace server, runs cost nothing.

    .pl.yaml
    project: platform
    roles:
      idle: { kind: worker, command: sleep infinity }
    schedules:
      nightly:
        cron: "0 1 * * *"
        branch: main
        run: scripts/ci/nightly.sh
        runner: { cpu: 14, memory: 32GiB, disk: 200GiB }
        timeout: 3h
        cache: [~/.cargo, target]
        environment: production
        secrets: [API_KEY]
    Commands
    # once: a workspace server with KVM, and the runner image (manual: scheduled jobs)
    pl nodes enroll --pool workspace --region lab1
    # the idle role needs an application node: ours on the Cloud plan,
    # or one of yours on the plan for your own servers
    pl nodes enroll --pool application --region lab1
    # then set PUSHLEFT_RUNNER_IMAGE in /etc/pushleft/agent.env and restart the agent
    pl secrets set API_KEY --production < api-key.txt
    pl schedules run nightly
    pl schedules logs nightly -f

    Mail and TURN on raw ports

    Use this for a service that does not speak HTTP, such as an SMTP server or a TURN relay.

    Pushleft forwards each port to one container. Previews never publish ports.

    A port can carry its own address, so outbound mail leaves from the address of its PTR record.

    .pl.yaml
    project: relay
    network:
      public_ports:
        - { port: 25, target_role: mx, target_port: 2525 }
        - { port: 3478, protocol: udp, target_role: turn, target_port: 3478 }
    roles:
      mx: { kind: private, port: 2525, health: tcp }
      turn: { kind: worker }
    production:
      regions: [fsn1]

    Write your .pl.yaml.

    Copy the recipe that fits, then run pl plan. It checks the manifest before anything deploys.

    Read the manifest → Add your own servers →