Skip to main content
Your spec tells slipway how to build and run your app. There are two ways to define it, and both are first-class — slipway reads the file live from your repo on every deploy.

slipway.yaml

The native manifest. Full control over services, ports, volumes, healthchecks, and secrets.

Docker Compose

Already have a docker-compose file? Slipway reads and converts it live — no slipway.yaml needed.

​
Where your spec comes from

Slipway picks a spec per repo, in this order:
SourceWhat it is
slipway.yaml (committed)The native manifest — full control over services, ports, volumes, healthchecks, and secrets.
docker-compose.yml (committed)Your existing Compose file. Slipway reads and converts it live on every deploy. See Docker Compose.
A committed slipway.yaml wins unless you explicitly pin a Compose file. Your repo is the source of truth: slipway never keeps an editable copy — it reads the file live on every push. The only thing you manage in the dashboard is the secret and variable values your spec references.
For a monorepo, set a per-component spec path (e.g. services/api/slipway.yaml) and slipway resolves the spec from there.

​
Minimal example

slipway.yaml
version: 1

services:
  web:
    build:
      context: .
    ports:
      - { port: 3000, public: true }
    healthcheck:
      readiness: { http: { path: /healthz, port: 3000 } }
A single service, built from a Dockerfile in the repo root, served at <env-name>-web-<id>.<your-apps-domain> on port 3000.

​
Top-level fields

FieldTypeRequiredNotes
versionintyesSpec version. Currently 1.
servicesmapyesNamed services. Keys match [a-z][a-z0-9-]{0,30}.
volumesmapnoNamed persistent volumes. See Volumes.
Everything else lives inside services.<name>.

Services

build, image, ports, env, healthcheck, depends_on.

Secrets & variables

${secret.NAME} and ${var.NAME} substitution and where you set the values.

Volumes

Persistent data, snapshots, and seeding previews from real data.

Examples

Worked specs for static sites, workers, and multi-service apps.

​
Validation

Slipway checks your spec in two places. At parse time — every push and PR, and when you add a repo to an environment. Catches missing required fields, invalid service names, a service with both build and image (or neither), duplicate public-port prefixes, and unknown keys (a typo like enviroment: fails immediately). These block the deploy before any infrastructure is touched. At deploy time — once a deploy starts. Catches missing ${secret.*} / ${var.*} references, unverified custom domains, bad ${service.*} references, and build / image-pull / healthcheck failures. These mark the deployment failed with the reason in the event log.

​
What slipway intentionally leaves out

Slipway is a preview tool, not a production platform. A few things are deliberately absent:
Not supportedDo this instead
replicas / autoscalingPreviews run one replica. Load-test elsewhere.
Init containers / sidecarsRun pre-start work from your startup command, or define a separate service.
Cron / job kindsTrigger one-off work on demand.
extends: / spec compositionNot yet — tell us if you need it.
A release: migration blockRun migrations from your container’s entrypoint, or shell in to a running container.

​
Stability

The spec is version: 1. New fields are additive and optional — your existing slipway.yaml keeps working. A breaking change would land as version: 2 with both parsers supported during a deprecation window.