---
title: "infra in devlanes.yaml"
url: https://devlanes.run/docs/reference/config/project/infra/
description: "Reference for the infra key in devlanes.yaml."
---

# infra in devlanes.yaml

A top-level key of [`devlanes.yaml`](/docs/reference/config/project/).

## `infra`

Type: mapping.

Containers the lanes depend on (databases, brokers, object stores), started and waited on before setup, tasks and services, plus the commands that create and remove each lane's data in them.

```yaml devlanes
infra:
  compose: docker-compose.yml
  hidden:
    - postgres
```

### `infra.compose`

Type: string or list of strings.

Compose file, or a list of files merged like repeated `-f`, relative to the project. Its services are shared by every lane unless listed in `per_lane`; the shared project runs from the primary worktree with the `.env` next to the project file there as `--env-file`.

```yaml devlanes
infra:
  compose: docker-compose.yml
```

### `infra.containers`

Type: mapping of names to mappings.

Docker containers run without a Compose file, keyed by name and reached as `infra.<name>` in expressions.

```yaml devlanes
infra:
  containers:
    cerbos:
      image: ghcr.io/cerbos/cerbos:0.40.0
      per_lane: true
      ports:
        http: 3592
```

### `infra.containers.<name>`

Type: mapping.

Docker container run without a Compose file, shared by every lane or one per lane. Processes reach it through `${{ infra.<name>.ports.<port> }}`.

```yaml devlanes
infra:
  containers:
    cerbos:
      image: ghcr.io/cerbos/cerbos:0.40.0
      per_lane: true
      ports:
        grpc: 3593
        http: 3592
```

### `infra.containers.<name>.command`

Type: string, list of strings or an [expression](/docs/reference/expressions/).

Command replacing the image's default: a list is used as is, a string runs through `/bin/sh -c` inside the container. In a list, an item that is one `${{ }}` expression giving a number or `true`/`false` becomes its text, such as `--port` followed by `${{ self.port }}`.

```yaml devlanes
infra:
  containers:
    cerbos:
      command:
        - server
        - --config=/policies/config.yaml
```

### `infra.containers.<name>.env`

Type: mapping of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Environment variables set inside the container.

```yaml devlanes
infra:
  containers:
    cerbos:
      env:
        LOG_LEVEL: debug
```

### `infra.containers.<name>.image`

Type: string or an [expression](/docs/reference/expressions/).

Image to run. Required. A running container with the same image, command, env, mounts and ports is reused; any change recreates it.

```yaml devlanes
infra:
  containers:
    cerbos:
      image: ghcr.io/cerbos/cerbos:0.40.0
```

### `infra.containers.<name>.per_lane`

Type: boolean or an [expression](/docs/reference/expressions/).

Run one container per lane instead of one shared by every lane. Defaults to false. Per-lane containers and their named volumes are removed by `devlanes lane clean`.

```yaml devlanes
infra:
  containers:
    cerbos:
      per_lane: true
```

### `infra.containers.<name>.ports`

Type: mapping of names to integers or [expressions](/docs/reference/expressions/).

Container ports by name. devlanes publishes each on a host port on 127.0.0.1, read as `${{ infra.<name>.ports.<port> }}`; `infra.<name>.port` is the first one.

```yaml devlanes
infra:
  containers:
    cerbos:
      ports:
        grpc: 3593
        http: 3592
```

### `infra.containers.<name>.ready`

Type: `started` or mapping.

Extra check the start waits for once the container is up (the image's healthcheck, else its first port accepting TCP), before setup, tasks and services run. Write `started` or one of `tcp`, `http`, `log` (matched against the container's logs) or `cmd` (run on the host). If it does not pass within its timeout (default 60s), the start fails.

Takes the same values and keys as [`services.<name>.ready`](/docs/reference/config/project/services/#services-name-ready).

```yaml devlanes
infra:
  containers:
    cerbos:
      ready: started
```

### `infra.containers.<name>.volumes`

Type: list of strings or [expressions](/docs/reference/expressions/).

Mounts as `source:destination[:mode]`. `./relative` and `/absolute` sources are bind mounts; relative ones start at the project file's directory, in the lane's worktree for a `per_lane` container and in the primary worktree for a shared one. A bare name is a named volume kept per project or per lane.

```yaml devlanes
infra:
  containers:
    cerbos:
      volumes:
        - ./infra/cerbos:/policies:ro
```

### `infra.env`

Type: mapping of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Variables for `${VAR}` interpolation in the Compose files only; processes do not see them (use `global_env` for those).

```yaml devlanes
infra:
  env:
    ACME_DB_PORT: 15432
```

### `infra.exclude`

Type: list of strings.

Compose services devlanes never starts, such as a local reverse proxy the devlanes proxy replaces.

```yaml devlanes
infra:
  exclude:
    - caddy
```

### `infra.external`

Type: mapping of names to mappings.

Servers you run yourself on a loopback port, such as pgAdmin, keyed by name. Every lane lists them, the proxy routes their hostnames, and machines connected with `devlanes remote connect` mirror them while a lane of the project runs. devlanes never starts or checks them. Put personal ones in `devlanes.local.yaml`.

```yaml devlanes
infra:
  external:
    pgadmin:
      address: 127.0.0.1:5050
      hosts: pgadmin.${{ lane.domain }}
```

### `infra.external.<name>`

Type: mapping.

A server you run yourself on a loopback port. Every lane of the project lists it, the proxy routes its hostnames to the port, and machines connected with `devlanes remote connect` mirror it while a lane of the project runs. The port is the same in every lane.

```yaml devlanes
infra:
  external:
    pgadmin:
      address: 127.0.0.1:5050
      hosts: pgadmin.${{ lane.domain }}
```

### `infra.external.<name>.address`

Type: string.

Where the server listens, `127.0.0.1:<port>` or `[::1]:<port>`. Only loopback addresses work. A port that devlanes or a lane already uses is an error. Required.

```yaml devlanes
infra:
  external:
    pgadmin:
      address: 127.0.0.1:5050
```

### `infra.external.<name>.hidden`

Type: boolean.

Keep the entry away from machines connected with `devlanes remote connect`. They never see, mirror or reach it. This machine still routes its hostnames. Defaults to false.

```yaml devlanes
infra:
  external:
    pgadmin:
      hidden: false
```

### `infra.external.<name>.hosts`

Type: string, mapping or an [expression](/docs/reference/expressions/), or a list of these.

Hostnames the devlanes HTTPS proxy routes to the port. One entry or a list. An entry is a hostname, or a mapping with `host` and optional `fallback` and `host_header`. Expressions can use `lane`, `project`, `infra` and `env`. Put the names under `${{ lane.domain }}` so each lane gets its own. The first host without a wildcard becomes the unit's URL.

```yaml devlanes
infra:
  external:
    pgadmin:
      hosts: pgadmin.${{ lane.domain }}
```

### `infra.external.<name>.hosts[].fallback`

Type: boolean or an [expression](/docs/reference/expressions/).

Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Defaults to false.

```yaml devlanes
infra:
  external:
    pgadmin:
      hosts:
        - host: pgadmin.${{ lane.domain }}
          fallback: true
```

### `infra.external.<name>.hosts[].host`

Type: string or an [expression](/docs/reference/expressions/). Required.

Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself. Quote it in YAML. Labels hold letters, digits and inner hyphens. Case and a trailing dot are ignored.

```yaml devlanes
infra:
  external:
    pgadmin:
      hosts:
        - host: pgadmin.${{ lane.domain }}
```

### `infra.external.<name>.hosts[].host_header`

Type: string.

Host header the server receives. Defaults to `preserve`, the hostname the browser asked for. `upstream` sends the address devlanes connects to, such as `127.0.0.1:5050`, for servers that only accept their own address.

Takes the same values as [`services.<name>.hosts[].host_header`](/docs/reference/config/project/services/#services-name-hosts-host_header).

```yaml devlanes
infra:
  external:
    pgadmin:
      hosts:
        - host: pgadmin.${{ lane.domain }}
          host_header: preserve
```

### `infra.hidden`

Type: list of strings.

Containers that machines connected with `devlanes remote connect` never see, mirror or reach.

```yaml devlanes
infra:
  hidden:
    - postgres
```

### `infra.hosts`

Type: mapping of names.

HTTPS hostnames for containers, keyed by Compose service or plain container name, so a browser can open a container's web port: a MinIO console or presigned S3 URLs, Mailpit, a mock OIDC provider. A hostname routes to the container's first published port unless its route sets `port`; each key takes one hostname or route, or a list.

```yaml devlanes
infra:
  hosts:
    s3mock: s3.${{ lane.domain }}
```

### `infra.hosts.<name>`

Type: string, mapping or an [expression](/docs/reference/expressions/), or a list of these.

HTTPS hostnames the devlanes proxy routes to this unit, so a browser reaches it at `https://<host>`: one hostname or route mapping, or a list of them.

Takes the same keys as [`services.<name>.hosts`](/docs/reference/config/project/services/#services-name-hosts).

```yaml devlanes
infra:
  hosts:
    s3mock: api.${{ lane.domain }}
```

### `infra.per_lane`

Type: list of strings.

Compose services run once per lane instead of shared, each in its own Compose project with ports from the lane's block and its own named volumes, removed by `devlanes lane clean`. Needs Compose 2.24.4 or newer.

```yaml devlanes
infra:
  per_lane:
    - mailpit
```

### `infra.profiles`

Type: list of strings.

Compose profiles to enable when resolving and starting the Compose services.

```yaml devlanes
infra:
  profiles:
    - development
```

### `infra.project_name`

Type: string or an [expression](/docs/reference/expressions/).

Name of the shared Compose project, fixed so `docker compose -p <name>` reaches the same containers outside devlanes. Defaults to the name Compose picks itself.

```yaml devlanes
infra:
  project_name: acme
```

### `infra.setup`

Type: mapping of names.

Named commands that prepare each lane's data, such as creating its database in a shared Postgres. They run once per lane after the containers are ready, all at the same time, and are recorded as done so later starts skip them; a failure stops the start unless the entry sets `ignore_errors`.

```yaml devlanes
infra:
  setup:
    database: docker compose exec -T postgres createdb acme_${{ lane.name }}
```

### `infra.setup.<name>`

Type: mapping, string, list of strings or an [expression](/docs/reference/expressions/).

Command that prepares (`setup`) or removes (`teardown`) a lane's data: a command string or list, or a mapping with `run` and options such as `container`, `ignore_errors` and `timeout`. Task `steps` can run it as `infra.setup.<name>` or `infra.teardown.<name>`.

```yaml devlanes
infra:
  setup:
    database: docker compose exec -T postgres createdb acme_${{ lane.name }}
```

### `infra.setup.<name>.container`

Type: string.

Run this setup entry again whenever the named container has restarted since it last ran, for data that lives in the container and may be gone, such as a RabbitMQ vhost.

```yaml devlanes
infra:
  setup:
    database:
      container: rabbitmq
```

### `infra.setup.<name>.cwd`

Type: string or an [expression](/docs/reference/expressions/).

Working directory, relative to the project file's directory in the lane's worktree; defaults to that directory.

```yaml devlanes
infra:
  setup:
    database:
      cwd: infra
```

### `infra.setup.<name>.env`

Type: mapping of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Variables for this command only.

```yaml devlanes
infra:
  setup:
    database:
      env:
        AWS_DEFAULT_REGION: us-east-1
```

### `infra.setup.<name>.ignore_errors`

Type: boolean or an [expression](/docs/reference/expressions/).

Count a failed or timed-out command as done instead of failing the start, for commands whose "already exists" error is fine. Defaults to false.

```yaml devlanes
infra:
  setup:
    database:
      ignore_errors: true
```

### `infra.setup.<name>.run`

Type: string, list of strings or an [expression](/docs/reference/expressions/).

Command to run: a string runs through `/bin/sh -c`, a list runs the program directly. Write the command you mean, such as `docker compose exec -T postgres ...`; devlanes runs it as written. Required. In a list, an item that is one `${{ }}` expression giving a number or `true`/`false` becomes its text, such as `--port` followed by `${{ self.port }}`.

```yaml devlanes
infra:
  setup:
    database:
      run: pnpm dev
```

### `infra.setup.<name>.timeout`

Type: [duration](/docs/reference/config/#durations) or an [expression](/docs/reference/expressions/).

Longest the command may run. When it runs out, the command is stopped (SIGTERM, then SIGKILL after 10 seconds) and counts as failed, so a setup entry fails the start unless `ignore_errors` is set. No limit by default.

```yaml devlanes
infra:
  setup:
    database:
      timeout: 15s
```

### `infra.teardown`

Type: mapping of names.

Named commands that remove a lane's data when the lane is cleaned (`devlanes lane clean`), one after another; never on stop. A failure is reported and the cleanup goes on.

```yaml devlanes
infra:
  teardown:
    database: docker compose exec -T postgres dropdb --if-exists acme_${{ lane.name }}
```

### `infra.teardown.<name>`

Type: mapping, string, list of strings or an [expression](/docs/reference/expressions/).

Command that prepares (`setup`) or removes (`teardown`) a lane's data: a command string or list, or a mapping with `run` and options such as `container`, `ignore_errors` and `timeout`. Task `steps` can run it as `infra.setup.<name>` or `infra.teardown.<name>`.

Takes the same keys as [`infra.setup.<name>`](/docs/reference/config/project/infra/#infra-setup-name).

```yaml devlanes
infra:
  teardown:
    database: docker compose exec -T postgres createdb acme_${{ lane.name }}
```
