Container services

A container service runs your code: either an image AppHaven builds from your repository, or a prebuilt image it pulls from a registry.

services:
  web:
    type: container
    image: ghcr.io/example/app:latest   # or use `build` (below) instead
    build:                    # build from source instead of pulling an image
      dockerfile: Dockerfile  # optional, default "Dockerfile"
      context: .              # optional, default repo root "."
      args:                   # optional, docker build args
        KEY: value
    ports:                    # optional, list of ints, 1–65535
      - 3000
    env:                      # optional, map of string -> string
      KEY: value
    volumes:                  # optional, list of mounts
      - name: <volume_name>
        mount_path: /abs/path
    healthcheck:              # optional, lets other services wait for "healthy"
      test: ["CMD-SHELL", "curl -fsS http://localhost:3000/ || exit 1"]
      interval: 10s
    depends_on:               # optional, start ordering
      - service: db
        condition: healthy

Field	Type	Required	Rules
image	string	conditional	Required unless build is set. Any image reference that can be pulled.
build	object	conditional	Build from source; see below. A container service declares image or build.
ports	list of int	no	Ports your service listens on. Each must be in the range 1–65535. See Networking.
env	map<string, string>	no	Environment variables for the container. See Environment variables.
volumes	list of {name, mount_path}	no	Storage mounts. See Volumes.
healthcheck	object	no	See Healthchecks.
depends_on	list of {service, condition}	no	Start ordering. See Start order.

Building from source (build)

Give a service a build block and AppHaven builds its image from your repository on every deploy, at the exact commit you deploy. No registry or build pipeline needed. The build log appears in the console's Builds tab.

Field	Type	Required	Rules
dockerfile	string	no	Path to the Dockerfile, relative to context. Default Dockerfile.
context	string	no	Build context directory, relative to the repo root. Default ..
args	map<string, string>	no	Docker build args.

A monorepo can build several services from one repository by giving each its own context:

services:
  api:
    type: container
    build:
      context: api
    ports:
      - 8080
  frontend:
    type: container
    build:
      context: frontend
    ports:
      - 3000

If a service sets both build and image, the image name is applied to the build result.

Healthchecks

A container service may declare a healthcheck, so other services can wait for it with depends_on: condition: healthy and the platform can report its readiness.

    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:3000/ || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s

Field	Type	Required	Rules
test	list of string	yes	["CMD", ...] (exec form) or ["CMD-SHELL", "<shell command>"]. The command runs inside your container.
interval	duration	no	Time between checks. Default 10s. Between 1s and 5m.
timeout	duration	no	Per-check timeout. Default 3s. Between 1s and 5m.
retries	int	no	Consecutive failures before the service counts as unhealthy. Default 3. Between 1 and 20.
start_period	duration	no	Grace period before failures count. Default 0s. Up to 5m.

A duration is a positive whole number followed by s or m, for example 10s or 5m (start_period also accepts 0s).

Where to go next

• Database: give your container a managed database.
• Volumes: durable storage for uploads, caches, and data.
• Environment variables: configuration and secrets.