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: 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
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

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:

​
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.