> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slipway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What the slipway spec is, where it comes from, and how it's validated.

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.

<CardGroup cols={2}>
  <Card title="slipway.yaml" icon="file-code" href="/slipway-yaml/services">
    The native manifest. Full control over services, ports, volumes, healthchecks, and secrets.
  </Card>

  <Card title="Docker Compose" icon="docker" href="/slipway-yaml/docker-compose">
    Already have a `docker-compose` file? Slipway reads and converts it live — no `slipway.yaml` needed.
  </Card>
</CardGroup>

## Where your spec comes from

Slipway picks a spec per repo, in this order:

| Source                               | What 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](/slipway-yaml/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.

<Note>
  For a monorepo, set a per-component spec path (e.g. `services/api/slipway.yaml`) and slipway resolves the spec from there.
</Note>

## Minimal example

```yaml slipway.yaml theme={"system"}
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

| Field      | Type | Required | Notes                                                           |
| ---------- | ---- | -------- | --------------------------------------------------------------- |
| `version`  | int  | yes      | Spec version. Currently `1`.                                    |
| `services` | map  | yes      | Named services. Keys match `[a-z][a-z0-9-]{0,30}`.              |
| `volumes`  | map  | no       | Named persistent volumes. See [Volumes](/slipway-yaml/volumes). |

Everything else lives inside `services.<name>`.

<CardGroup cols={2}>
  <Card title="Services" icon="cube" href="/slipway-yaml/services">
    `build`, `image`, `ports`, `env`, `healthcheck`, `depends_on`.
  </Card>

  <Card title="Secrets & variables" icon="key" href="/slipway-yaml/secrets-and-variables">
    `${secret.NAME}` and `${var.NAME}` substitution and where you set the values.
  </Card>

  <Card title="Volumes" icon="database" href="/slipway-yaml/volumes">
    Persistent data, snapshots, and seeding previews from real data.
  </Card>

  <Card title="Examples" icon="rectangle-code" href="/slipway-yaml/examples">
    Worked specs for static sites, workers, and multi-service apps.
  </Card>
</CardGroup>

## 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](/deployments/watching).

## What slipway intentionally leaves out

Slipway is a preview tool, not a production platform. A few things are deliberately absent:

| Not supported                 | Do this instead                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `replicas` / autoscaling      | Previews run one replica. Load-test elsewhere.                                                                      |
| Init containers / sidecars    | Run pre-start work from your startup command, or define a separate service.                                         |
| Cron / job kinds              | Trigger one-off work on demand.                                                                                     |
| `extends:` / spec composition | Not yet — tell us if you need it.                                                                                   |
| A `release:` migration block  | Run migrations from your container's entrypoint, or [shell in](/deployments/watching#shell) 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.