Services - slipway

A service is one entry under services:. This page documents every field, grouped by what it does. For a one-row-each lookup, see the field index.

slipway.yaml

version: 1

services:
  - name: api
    runtime: docker
    ports:
      - port: 8080
        public: true
    healthCheckPath: /healthz

Identity

Field	Description
`name`	The service name
`type`	What kind of service it is
`enabled`	Whether it runs at all

name

Required. The service name, matching ^[a-z][a-z0-9-]{0,30}$. Siblings reach the service by this name, so it must be unique across the whole project, not only within one spec. slipway refuses to deploy a service whose name another source already publishes.

type

Optional. One of web, worker, cron or static. If you omit it, the service is a web service. The type decides which other fields apply. See Service types.

enabled

Optional. Defaults to true. Setting it to false keeps the configuration and tears the workload down on the next deploy, which is how you park a service without deleting it.

Source

A service either runs an image you already built, or builds from source. Declare one or the other, never both.

Field	Description
`image`	Run a prebuilt image
`rootDir`	Where the build runs
`dockerfilePath`	Which Dockerfile to build
`dockerContext`	Narrow the build context
`dockerTarget`	Which build stage to stop at
`buildArgs`	Build-time arguments
`runtime`	Build without a Dockerfile
`runtimeVersion`	Pin the language version
`buildCommand`	The build step

image

Optional. A pullable image reference such as ghcr.io/acme/api:1.2. Mutually exclusive with every build field. Rejected on type: static, which has no container. The reference is resolved and pinned at deploy time, so pushing a new image to the same tag does not redeploy anything. See Deploy from an image.

rootDir

Optional. The directory the build runs in, relative to the repository root. Defaults to . when the service builds. dockerfilePath and publish are relative to it.

dockerfilePath

Optional. The Dockerfile to build, relative to rootDir. Mutually exclusive with runtime, because a language runtime generates its own Dockerfile. Rejected on static.

dockerContext

Optional. Narrows the Docker build context below rootDir, for when the Dockerfile needs to see less than the whole directory. Rejected on static.

dockerTarget

Optional. The build stage to stop at, matching ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Empty means the last stage. Mutually exclusive with runtime. Rejected on static.

buildArgs

Optional. A map of build-time arguments. Values may carry ${secret.*}, ${var.*} and ${service.*} references. Resolved values are passed to the build as arguments and never appear on the build command line.

A build argument your Dockerfile writes to disk is baked into the image layer. Keep credentials out of build args unless the Dockerfile consumes them in the same RUN step.

runtime

Optional. Either docker, meaning build the committed Dockerfile, or a language runtime: node, python, go, ruby, rust or elixir. See Language runtimes.

runtimeVersion

Optional. Pins the language version, such as "22" or "3.12". Requires runtime, and must be one that runtime offers. If you omit it, slipway uses the runtime’s default, which moves up over time.

buildCommand

Optional. The build step a language runtime or a static site runs after installing dependencies, such as npm run build. The service’s env is available to it, and to the dependency install before it. A language runtime passes every value as a BuildKit secret mounted on those steps, so next build can inline NEXT_PUBLIC_* values and npm ci can read a registry token, without any of it being written into the image. Changing a value rebuilds those steps. A committed Dockerfile receives a value by declaring its name with ARG, or mounts it as a secret; see how values reach the build. This is not the start command. Use command for that.

Networking

Field	Description
`ports`	Ports the container listens on
`prefix`	The subdomain label
`domain`	The zone to serve under
`auth`	The sign-in wall in front of the public URL

ports

Optional, type: web only. The ports the container listens on.

slipway.yaml

    ports:
      - port: 3000
        public: true
      - port: 9090

Each port is 1 to 65535. At most one port per service may be public: true. A public port gives the service a hostname at the edge; every other port is reachable by siblings only. Rejected on worker, cron and static.

prefix

Optional. The subdomain label the service is served at, matching ^[a-z][a-z0-9-]{0,30}$. Defaults to the service name. Requires a public surface, meaning a public port or a static site. Without one, validation fails with prefix/domain need a public hostname. Unique per zone across your organization.

domain

Optional. A zone your organization has claimed and verified. Same requirements as prefix. prefix and domain sit on the service, not inside a port entry. See Custom domains.

auth

Optional. Requires visitors to sign in before they reach the service.

slipway.yaml

    auth:
      token: true
      members: true

token asks for the shared token generated under the project’s Settings → Access. members asks the visitor to sign in with GitHub or GitLab and belong to the upstream account your organization is connected to. Turn on either or both; a visitor gets in through whichever they can satisfy. Both default to false. Requires a public port. Rejected on worker, cron and static. The service’s Auth tab in the console overrides this block for that project, in both directions. See Access controls.

Configuration

Field	Description
`env`	Environment variables
`command`	Override the entrypoint
`args`	Override the arguments
`workDir`	The working directory
`files`	Mount a file from the repo
`dependsOn`	Wait for another service
`preDeploy`	Run a job before the rollout
`maxShutdownDelaySeconds`	The shutdown grace period
`schedule`	When a cron service runs
`timeout`	How long one cron run may take
`concurrencyPolicy`	What a cron slot does while a run is still going
`maxConcurrentRuns`	How many cron runs may overlap

env

Optional. A map of environment variables. Values may carry ${secret.*}, ${var.*} and ${service.*} references, resolved at deploy time.

slipway.yaml

    env:
      DATABASE_URL: ${service.db.url}
      STRIPE_KEY: ${secret.STRIPE_KEY}
      LOG_LEVEL: info

A literal in the spec always wins over a stored value of the same name. See Secrets and variables. On a static site, env applies to the build only, and anything referenced ends up inside the built files.

command

Optional. A list overriding the image’s entrypoint.

slipway.yaml

    command: ["node", "dist/server.js"]

Rejected on static.

args

Optional. A list overriding the image’s arguments. Rejected on static.

workDir

Optional. An absolute path used as the working directory. Rejected on static.

files

Optional. A list of "<repo-path>:<container-path>" entries, mounting a file from the repository into the container.

slipway.yaml

    files:
      - "config/nginx.conf:/etc/nginx/nginx.conf"

The source is relative to the spec directory and may not escape it with .., be absolute, or start with ~. The target must be absolute. Each file is limited to about 1 MB. Rejected on static.

dependsOn

Optional. A list of sibling service names this service waits for.

slipway.yaml

    dependsOn: [db, cache]

Each name must exist, must not be this service, and must not be disabled, cron or static. The dependency graph must be acyclic; a cycle is reported as a → b → a. It waits for readiness, not for correctness. A database accepting connections before its migrations have run still counts as ready. Rejected on cron and static.

preDeploy

Optional. A command run as a one-shot job in the freshly built image, with the service’s resolved environment, before the rollout.

slipway.yaml

    preDeploy: ["npm", "run", "migrate"]

The deploy proceeds only if it exits 0. This is where migrations belong. Rejected on static.

maxShutdownDelaySeconds

Optional. How long the container gets to exit after receiving SIGTERM, from 1 to 300. 0 means the platform default of 30 seconds. Use it for a worker that must finish an in-flight task. Rejected on cron and static.

schedule

Required on type: cron, rejected everywhere else. A five-field cron expression in UTC.

slipway.yaml

  - name: nightly
    type: cron
    schedule: "0 3 * * *"
    runtime: docker
    command: ["node", "scripts/nightly.js"]

No seconds field, and no descriptors such as @daily. Each run is a one-off job: it starts from the deployed image (or command), and when it exits it is gone. You are billed for each run’s own duration. The first run happens at the first slot after a deploy, never on the deploy itself. To run one immediately, use Deploy → Run now on the service; it follows the same concurrencyPolicy as a slot. A run in progress can be stopped from the service’s Scheduled runs list; it is recorded as cancelled. Deploying a new version stops any run of the previous one, recorded as cancelled with “replaced by a new deploy”, so a fix never leaves the broken build running. Missed slots are not caught up: if slipway’s control plane was down across several slots, only the most recent one runs when it is back. A schedule change takes effect on the next deploy. These fields can also be edited on the service’s Settings tab.

timeout

Optional, type: cron only. How long one run may take, as a duration such as 30m or 2h. A run still going at the timeout is stopped and recorded as failed. Between 10s and 24h; the default is 1h.

slipway.yaml

    timeout: 2h

concurrencyPolicy

Optional, type: cron only. What happens when a slot (or Run now) comes due while a previous run is still going:

Value	Behavior
`skip` (default)	The new run is recorded as skipped; the running one continues.
`allow`	The new run starts alongside, up to `maxConcurrentRuns`.
`replace`	The running run is stopped and recorded as cancelled, and the new one starts.

maxConcurrentRuns

Optional, concurrencyPolicy: allow only. How many runs may be going at once, from 1 to 10; the default is 10. A slot that finds this many running is skipped.

slipway.yaml

    concurrencyPolicy: allow
    maxConcurrentRuns: 3

Health

Field	Description
`healthCheckPath`	A simple HTTP readiness check
`healthcheck`	Full probe configuration

healthCheckPath

Optional, type: web only. A path that must return 2xx before the service takes traffic.

slipway.yaml

    healthCheckPath: /healthz

Must start with /, and the service must declare a port to probe. Mutually exclusive with healthcheck. The path is probed on the public port, or the first declared port. Keep it cheap: a check that itself waits on a database fails the deploy whenever the database is slow.

healthcheck

Optional, web and worker. Full control over three probes.

slipway.yaml

    healthcheck:
      startup:
        http: { path: /healthz, port: 8080 }
        failureThreshold: 30
        periodSeconds: 2
      readiness:
        http: { path: /ready, port: 8080 }
      liveness:
        tcp: { port: 8080 }

Each probe declares exactly one of:

Kind	Fields
`http`	`path` (required, absolute) and `port`
`tcp`	`port`
`exec`	`command`, a list
`grpc`	`port` and `service`

Each also accepts periodSeconds, timeoutSeconds, failureThreshold, successThreshold and initialDelaySeconds. Use a startup probe for a slow boot rather than stretching readiness. Rejected on cron and static.

Compute

Field	Description
`cpu` and `memory`	The allocation
`replicas`	A fixed pod count
`scaling`	Autoscaling
`autoResize`	Automatic compute

cpu

Optional. A number of cores (1, 0.5) or a millicore string ("500m"). Minimum 100m, in multiples of 50m. Defaults to 500m. Rejected on static.

memory

Optional. 512MB, 1GB, 512Mi or 1Gi. Minimum 128Mi, in multiples of 128Mi. Defaults to 512Mi. Decimal suffixes are normalised to binary. Rejected on static. See CPU and memory.

replicas

Optional, web and worker. A fixed pod count from 0 to 20. Defaults to 1. Mutually exclusive with scaling, and cannot exceed 1 on a service with a disk.

scaling

Optional, web and worker. Autoscaling between a floor and a ceiling.

slipway.yaml

    scaling:
      min: 2
      max: 10
      targetCPUPercent: 70

min is 1 or more, max is at least min and at most 20, and the two targets are 0 to 100. If neither target is set, slipway uses a CPU target of 70. See Scaling.

autoResize

Optional, web and worker. Grows the allocation under sustained pressure.

slipway.yaml

    autoResize:
      maxCPU: 2
      maxMemory: 4GB

Writing the block is the opt-in. See Automatic compute for every tuning field.

Storage

disk

Optional, web and worker. Persistent storage for this service.

slipway.yaml

    disk:
      mountPath: /var/lib/app/uploads
      sizeGB: 10

mountPath is absolute and cannot be /. sizeGB is 1 to 1024. One disk per service, no sharing, and a service with a disk runs a single pod. Rejected on cron and static. See Disks.

Previews

previews

Optional, web and worker. Overrides applied only inside a preview.

slipway.yaml

    previews:
      cpu: "500m"
      memory: 512MB
      env:
        STRIPE_KEY: ${secret.STRIPE_TEST_KEY}

env is merged over the service’s env before resolution. Rejected on cron and static.

Static sites

publish, notFound, redirects and headers apply to type: static only. See Static sites.

Field index

Every field, one row each.

Examples

Worked specs for common shapes.

​Identity

​name

​type

​enabled

​Source

​image

​rootDir

​dockerfilePath

​dockerContext

​dockerTarget

​buildArgs

​runtime

​runtimeVersion

​buildCommand

​Networking

​ports

​prefix

​domain

​auth

​Configuration

​env

​command

​args

​workDir

​files

​dependsOn

​preDeploy

​maxShutdownDelaySeconds

​schedule

​timeout

​concurrencyPolicy

​maxConcurrentRuns

​Health

​healthCheckPath

​healthcheck

​Compute

​cpu

​memory

​replicas

​scaling

​autoResize

​Storage

​disk

​Previews

​previews

​Static sites

​Related

Field index

Examples

Identity

name

type

enabled

Source

image

rootDir

dockerfilePath

dockerContext

dockerTarget

buildArgs

runtime

runtimeVersion

buildCommand

Networking

ports

prefix

domain

auth

Configuration

env

command

args

workDir

files

dependsOn

preDeploy

maxShutdownDelaySeconds

schedule

timeout

concurrencyPolicy

maxConcurrentRuns

Health

healthCheckPath

healthcheck

Compute

cpu

memory

replicas

scaling

autoResize

Storage

disk

Previews

previews

Static sites

Related