Skip to content
GuvDocs

environments.<name>.services

View as Markdown

Per-service overrides for this environment (deep-merged over the base service).

  • Type: map of names to object
  • Since: manifest v1

Example

Section titled “Example”
environments:
  production:
    services:
      web:
        replicas: 1
        resources:
          cpu: 0.5
          memory: 512MB

Fields

Section titled “Fields”

description

Section titled “description”

environments.<name>.services.<name>.description

What the service does, shown in the dashboard.

  • Type: string
  • Maximum length: 500
  • Since: manifest v1
environments:
  production:
    services:
      web:
        description: Public website and dashboard

root

Section titled “root”

environments.<name>.services.<name>.root

Directory of the service in the repository.

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        root: apps/web

watch

Section titled “watch”

environments.<name>.services.<name>.watch

Globs of paths that trigger a rebuild on push. Defaults to <root>/** plus shared lockfiles.

  • Type: list of string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        watch:
          - apps/web/**
          - packages/ui/**
          - pnpm-lock.yaml

build

Section titled “build”

environments.<name>.services.<name>.build

How the service is built. Without this block Guv detects a Dockerfile or uses Railpack.

  • Type: object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          builder: dockerfile
          dockerfile: services/api/Dockerfile

builder

Section titled “builder”

environments.<name>.services.<name>.build.builder

railpack auto-detects the stack, dockerfile builds a Dockerfile, image deploys a prebuilt image.

  • Type: railpack, dockerfile, image
  • Default: railpack
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          builder: dockerfile

dockerfile

Section titled “dockerfile”

environments.<name>.services.<name>.build.dockerfile

Path to the Dockerfile, relative to the repository root.

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          dockerfile: services/api/Dockerfile

context

Section titled “context”

environments.<name>.services.<name>.build.context

Build context directory, relative to the repository root. Defaults to root.

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          context: services/api

image

Section titled “image”

environments.<name>.services.<name>.build.image

Image to deploy when builder is image (Docker Hub, GHCR or a private registry).

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          image: ghcr.io/acme/api:1.4.2

registry_credentials

Section titled “registry_credentials”

environments.<name>.services.<name>.build.registry_credentials

Secret holding credentials for a private registry.

  • Type: string
  • Pattern: ^secret://[A-Za-z_][A-Za-z0-9_-]{0,127}$
  • Since: manifest v1
environments:
  production:
    services:
      web:
        build:
          registry_credentials: secret://ghcr-token

start

Section titled “start”

environments.<name>.services.<name>.start

Start command. Detected when omitted.

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        start: pnpm --filter web start

pre_deploy

Section titled “pre_deploy”

environments.<name>.services.<name>.pre_deploy

Command run once per deployment, in a separate VM with the same variables, before traffic moves (for migrations). Failure stops the rollout.

  • Type: string
  • Since: manifest v1
environments:
  production:
    services:
      web:
        pre_deploy: pnpm --filter db migrate deploy

port

Section titled “port”

environments.<name>.services.<name>.port

Port the app listens on. Services with a port get a generated domain unless private.

  • Type: integer
  • Range: 1 to 65535
  • Since: manifest v1
environments:
  production:
    services:
      web:
        port: 3000

healthcheck

Section titled “healthcheck”

environments.<name>.services.<name>.healthcheck

How Guv decides a new deployment is healthy before moving traffic. A string is shorthand for an HTTP path.

  • Type: string or object
  • Since: manifest v1

Accepted forms

  • string
  • object: the full form, with the fields below
environments:
  production:
    services:
      web:
        healthcheck: /healthz
environments:
  production:
    services:
      web:
        healthcheck:
          path: /healthz
          timeout: 10s

type

Section titled “type”

environments.<name>.services.<name>.healthcheck.type

HTTP GET expecting 2xx/3xx, or a TCP connect.

  • Type: http, tcp
  • Default: http
  • Since: manifest v1
environments:
  production:
    services:
      web:
        healthcheck:
          type: http

path

Section titled “path”

environments.<name>.services.<name>.healthcheck.path

Path for HTTP checks.

  • Type: string
  • Default: /
  • Pattern: ^/
  • Since: manifest v1
environments:
  production:
    services:
      web:
        healthcheck:
          path: /healthz

port

Section titled “port”

environments.<name>.services.<name>.healthcheck.port

Port to check; defaults to the service port.

  • Type: integer
  • Range: 1 to 65535
  • Since: manifest v1
environments:
  production:
    services:
      web:
        healthcheck:
          port: 3000

timeout

Section titled “timeout”

environments.<name>.services.<name>.healthcheck.timeout

Per-check timeout (up to 60s).

environments:
  production:
    services:
      web:
        healthcheck:
          timeout: 10s

interval

Section titled “interval”

environments.<name>.services.<name>.healthcheck.interval

Time between checks.

environments:
  production:
    services:
      web:
        healthcheck:
          interval: 10s

start_timeout

Section titled “start_timeout”

environments.<name>.services.<name>.healthcheck.start_timeout

How long a new deployment has to become healthy (up to 15m).

environments:
  production:
    services:
      web:
        healthcheck:
          start_timeout: 5m

domains

Section titled “domains”

environments.<name>.services.<name>.domains

Custom domains. They attach to the production environment unless set under environments.<env>.services.<svc>.domains.

  • Type: list of hostname or object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        domains:
          - www.primecarers.co.uk
          - primecarers.co.uk

host

Section titled “host”

environments.<name>.services.<name>.domains[].host

Hostname.

  • Type: hostname
  • Required: yes
  • Since: manifest v1
environments:
  production:
    services:
      web:
        domains:
          - host: primecarers.co.uk

redirect_to

Section titled “redirect_to”

environments.<name>.services.<name>.domains[].redirect_to

Redirect every request to this hostname (permanent redirect), instead of serving.

environments:
  production:
    services:
      web:
        domains:
          - redirect_to: www.primecarers.co.uk

private

Section titled “private”

environments.<name>.services.<name>.private

No public domain; reachable only on the environment’s private network as <name>.guv.internal.

  • Type: boolean
  • Default: false
  • Since: manifest v1
environments:
  production:
    services:
      web:
        private: true

replicas

Section titled “replicas”

environments.<name>.services.<name>.replicas

Number of copies. An integer fixes the count; an object enables autoscaling.

  • Type: integer or object
  • Since: manifest v1

Accepted forms

  • integer
  • object: the full form, with the fields below
environments:
  production:
    services:
      web:
        replicas: 2
environments:
  production:
    services:
      web:
        replicas:
          min: 2
          max: 6
          scale_on:
            cpu: 70%

min

Section titled “min”

environments.<name>.services.<name>.replicas.min

Fewest replicas. 0 allows scaling to zero.

  • Type: integer
  • Default: 1
  • Range: 0 to 20
  • Since: manifest v1
environments:
  production:
    services:
      web:
        replicas:
          min: 2

max

Section titled “max”

environments.<name>.services.<name>.replicas.max

Most replicas.

  • Type: integer
  • Range: 1 to 20
  • Since: manifest v1
environments:
  production:
    services:
      web:
        replicas:
          max: 6

scale_on

Section titled “scale_on”

environments.<name>.services.<name>.replicas.scale_on

Targets for horizontal autoscaling between min and max.

  • Type: object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        replicas:
          scale_on:
            cpu: 70%
            concurrency: 80

resources

Section titled “resources”

environments.<name>.services.<name>.resources

Limits per replica. You are billed for actual use, not for limits.

  • Type: object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        resources:
          cpu: 1
          memory: 1GB

cpu

Section titled “cpu”

environments.<name>.services.<name>.resources.cpu

vCPU limit, in steps of 0.1.

  • Type: number
  • Range: 0.1 to 32
  • Since: manifest v1
environments:
  production:
    services:
      web:
        resources:
          cpu: 1
environments:
  production:
    services:
      web:
        resources:
          cpu: 0.5

memory

Section titled “memory”

environments.<name>.services.<name>.resources.memory

Memory limit (at least 128MB).

  • Type: size
  • Since: manifest v1
environments:
  production:
    services:
      web:
        resources:
          memory: 1GB

sleep_when_idle

Section titled “sleep_when_idle”

environments.<name>.services.<name>.sleep_when_idle

Scale to zero after 10 minutes without requests; the next request wakes it in 1–3 seconds.

  • Type: boolean
  • Since: manifest v1
environments:
  production:
    services:
      web:
        sleep_when_idle: false

env

Section titled “env”

environments.<name>.services.<name>.env

Variables for this service.

  • Type: env
  • Since: manifest v1

volumes

Section titled “volumes”

environments.<name>.services.<name>.volumes

Volumes to mount. A service with a single-server volume runs one replica.

  • Type: list of object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        volumes:
          - name: rota-cache
            mount: /data

name

Section titled “name”

environments.<name>.services.<name>.volumes[].name

Volume name.

  • Type: name
  • Required: yes
  • Since: manifest v1
environments:
  production:
    services:
      web:
        volumes:
          - name: rota-cache

mount

Section titled “mount”

environments.<name>.services.<name>.volumes[].mount

Absolute mount path inside the service.

  • Type: string
  • Required: yes
  • Pattern: ^/
  • Since: manifest v1
environments:
  production:
    services:
      web:
        volumes:
          - mount: /data

cron

Section titled “cron”

environments.<name>.services.<name>.cron

Five-field cron schedule. Makes the service a scheduled job; you are billed for run time only.

  • Type: string
  • Pattern: ^(@(hourly|daily|weekly|monthly|yearly)|(\S+\s+){4}\S+)$
  • Since: manifest v1
environments:
  production:
    services:
      web:
        cron: 0 2 * * *

timezone

Section titled “timezone”

environments.<name>.services.<name>.timezone

IANA time zone for cron.

  • Type: string
  • Default: Europe/London
  • Since: manifest v1
environments:
  production:
    services:
      web:
        timezone: Europe/London

timeout

Section titled “timeout”

environments.<name>.services.<name>.timeout

Maximum run time of each cron run.

environments:
  production:
    services:
      web:
        timeout: 30m

concurrency_policy

Section titled “concurrency_policy”

environments.<name>.services.<name>.concurrency_policy

What to do if a cron run is still going when the next is due.

  • Type: forbid, allow, replace
  • Default: forbid
  • Since: manifest v1
environments:
  production:
    services:
      web:
        concurrency_policy: forbid

restart

Section titled “restart”

environments.<name>.services.<name>.restart

Restart behaviour when the process exits.

  • Type: object
  • Since: manifest v1
environments:
  production:
    services:
      web:
        restart:
          policy: on_failure
          max_retries: 10

policy

Section titled “policy”

environments.<name>.services.<name>.restart.policy

When to restart.

  • Type: on_failure, always, never
  • Default: on_failure
  • Since: manifest v1
environments:
  production:
    services:
      web:
        restart:
          policy: on_failure

max_retries

Section titled “max_retries”

environments.<name>.services.<name>.restart.max_retries

Restarts before the service is marked crashed.

  • Type: integer
  • Default: 10
  • Range: 0 to 100
  • Since: manifest v1
environments:
  production:
    services:
      web:
        restart:
          max_retries: 10

overlap

Section titled “overlap”

environments.<name>.services.<name>.overlap

How long the previous deployment keeps serving after traffic moves.

environments:
  production:
    services:
      web:
        overlap: 20s

auto_rollback

Section titled “auto_rollback”

environments.<name>.services.<name>.auto_rollback

Roll back automatically if a new deployment crash-loops or fails health checks. Defaults to true in production.

  • Type: boolean
  • Since: manifest v1
environments:
  production:
    services:
      web:
        auto_rollback: true

See also

Section titled “See also”