Format
Compose files define the services that make up your app. Each service specifies an image, and optionally environment variables, volumes, ports, health checks, and resource limits.
services:
app:
image: example/app:1.0.0
environment:
TZ: ${TIMEZONE:-UTC}
ports:
- "8080:80"
volumes:
- ./data:/app/data
deploy:
resources:
limits:
memory: 512M
Value Formats
Volume paths — Relative paths (e.g., ./data:/app/data) resolve against the instance's data/ directory. Absolute paths are used as-is.
Duration values — 10s, 2m, 1h, or a plain number (interpreted as seconds).
Memory values — 512M, 2G, 1024m, or a plain number (interpreted as MB).
Compose Specification Compatibility
Lawn aims to be compatible with the Compose Specification . The tables below show the current state.
pre_start steps cause an error.Supported Fields
| Field | Description |
|---|---|
services.<name>.image | Container image with tag |
services.<name>.entrypoint | Override the image entrypoint |
services.<name>.command | Override the image command arguments |
services.<name>.pre_start | Ordered initialization containers |
services.<name>.working_dir | Override the working directory |
services.<name>.user | Run as specific user (UID, UID:GID) |
services.<name>.environment | Environment variables (mapping syntax only) |
services.<name>.volumes | Volume mounts (short syntax: host:container[:ro]) |
services.<name>.ports | Port mappings (short syntax: host:container[/protocol]) |
services.<name>.depends_on | Service dependencies (list syntax only) |
services.<name>.healthcheck | Health check (test, interval, timeout, retries, start_period) |
services.<name>.deploy.resources.limits | Resource constraints (cpus, memory) |
Unsupported Fields
| Category | Fields |
|---|---|
| Build | build, dockerfile, context |
| Networking | networks, network_mode, dns, dns_search, extra_hosts, hostname, domainname |
| Named volumes | Top-level volumes key, named volume references |
| Configs & secrets | configs, secrets |
| Scaling | scale, deploy.replicas |
| Restart | restart, deploy.restart_policy |
| Logging | logging, driver, options |
| Security | cap_add, cap_drop, privileged, security_opt, read_only |
| Process | init, stop_signal, stop_grace_period |
| Other | labels, stdin_open, tty, tmpfs, shm_size, env_file, profiles, links, ulimits, sysctls, group_add |
| Conditional depends_on | depends_on with condition and restart keys (use plain list syntax instead) |
| Long syntax | Long-form volumes and ports |
Initialization
Available since Lawn 0.6.1. Use pre_start for migrations or setup that must finish before a service starts:
services:
app:
image: example/app:1.0
depends_on: [postgres]
volumes:
- ./data:/app/data
pre_start:
- command: ["sh", "-c", "./migrate.sh"]
- image: alpine:3.22
command: ["sh", "-c", "echo ready > /app/data/ready"]
Steps run in order after dependencies are ready. Each uses a temporary container with the service's mounts and network access. Every step must exit 0 before the service and its dependents can start. A failed step appears in the service's failure details and logs; healthy dependencies and independent services keep running.
| Step field | Behavior |
|---|---|
image | Use this image instead of the service image. |
command | Replace the chosen image's command, retaining its entrypoint. Strings split on whitespace outside quotes without adding a shell; omission uses image defaults. |
environment | Add or override service environment values. Accepts a mapping or a list of NAME=value strings. |
user | Override the process user with a numeric UID or UID:GID. With no image override, inherit the service user; otherwise use the chosen image's default. |
working_dir | Override the service's working directory. |
Initialization runs again whenever Lawn recreates a service, including app Restart and app updates. Reconnecting to surviving containers does not rerun it. After a failure, an explicit Start retries the entire sequence. Stop and removal cancel active initialization.
Lawn copies initFiles before the first step. Changes to shared mounts remain available to subsequent steps and the main service. Each step has its own temporary root filesystem; changes outside shared mounts are discarded.
Lawn rejects malformed steps, unknown step fields, privileged: true, and per_replica: false. Set x-lawn.compatibility.minLawnVersion to 0.6.1 or later in templates that use initialization.