docker-compose.yml fields
Our compose-file support is currently based on version 2.4, as such any fields that were introduced in version 3 are not supported.
Supported fields
| Field | Details |
|---|---|
| build | when using a path it must point to project/app subfolders. URLs to git repositories are not currently supported. |
| build.context | must point to project/app subfolders. URLs to git repositories are not currently supported. |
| build.dockerfile | |
| build.args | |
| build.cache_from | |
| build.extra_hosts | |
| build.labels | |
| build.shm_size | |
| build.target | currently incompatible with Livepush |
| cap_add | |
| cap_drop | |
| cgroup_parent | |
| command | |
| cpu_shares | |
| cpu_quota | |
| cpuset | |
| devices | |
| depends_on | Only array form and service_started condition |
| dns | |
| dns_opt | |
| dns_search | |
| domainname | |
| entrypoint | |
| environment | |
| expose | |
| extra_hosts | |
| group_add | |
| healthcheck | |
| hostname | |
| image | |
| ipc | |
| labels | |
| mac_address | |
| mem_limit | |
| mem_reservation | |
| network_mode | Only support bridge, host, service:[service name], or none |
| networks | Only support specifying network names |
| oom_kill_disable | |
| oom_score_adj | |
| pid | Only support host or none |
| pids_limit | |
| ports | |
| privileged | |
| read_only | |
| restart | Defaults to always |
| security_opt | |
| shm_size | |
| stop_grace_period | |
| stop_signal | |
| sysctls | |
| tmpfs | |
| ulimits | |
| user | |
| userns_mode | |
| volumes | Only support short syntax and named volumes. Bind mounts are not supported, except for as allowed by balena specific labels |
| working_dir |
Known unsupported fields
| Field | Details |
|---|---|
| build.isolation | |
| build.network | |
| blkio_config | |
| container_name | Used by the device supervisor |
| cpu_count | |
| cpu_percent | |
| cpus | Introduced by Docker Compose v2.2 and therefore not working |
| env_file and service.env_file | |
| external_links | |
| isolation | |
| links | |
| logging | |
| memswap_limit | |
| mem_swappiness | |
| runtime | |
| scale | |
| stdin_open | |
| tty | |
| volume_driver | |
| volumes_from |
Known unsupported features
| Feature | Details |
|---|---|
| variable substitution |
Labels
Note: If you have devices in your app that have a supervisor version lower than 7.22.0, then you should use the io.resin.features. form of the labels to ensure that all devices obey the label. Earlier supervisor versions will not understand the io.balena.features label.
| Label | Default | Description | Supervisor | balenaOS* |
|---|---|---|---|---|
| io.balena.features.balena-socket | false | Bind mounts the balena container engine socket into the container and sets the environment variable DOCKER_HOST with the socket location for use by docker clients. |
v7.23.0 | v2.21.0 |
| io.balena.features.dbus | false | Bind mounts the host OS dbus into the container using /run/dbus:/host/run/dbus. |
v7.23.0 | v2.21.0 |
| io.balena.features.sysfs | false | Bind mounts the host OS /sys into the container. |
v10.8.0 | v2.48.0 |
| io.balena.features.procfs | false | Bind mounts the host OS /proc into the container. |
v10.8.0 | v2.48.0 |
| io.balena.features.kernel-modules | false | Bind mounts the host OS /lib/modules into the container (i.e. /lib/modules:/lib/modules). |
v7.23.0 | v2.21.0 |
| io.balena.features.firmware | false | Bind mounts the host OS /lib/firmware into the container. |
v7.23.0 | v2.21.0 |
| io.balena.features.journal-logs | false | Bind mounts journal log directories /var/log/journal and /run/log/journal as well as /etc/machine-id in read only mode. Required by some logging agents such as promtail. Journal logs can be read using libraries such as sd-journal in C or sdjournal in Go. |
v12.0.1 | v2.61.0 |
| io.balena.features.supervisor-api | false | Ensures that BALENA_SUPERVISOR_HOST, BALENA_SUPERVISOR_PORT, BALENA_SUPERVISOR_ADDRESS, and BALENA_SUPERVISOR_API_KEY are added to the container environment variables, so the supervisor API can be used. |
v7.23.0 | v2.21.0 |
| io.balena.features.balena-api | false | When enabled, it will make sure that BALENA_API_KEY is added to the container environment variables. |
v7.23.0 | v2.21.0 |
| io.balena.update.strategy | download-then-kill | Set the fleet update strategy. | v7.23.0 | v2.21.0 |
| io.balena.update.handover-timeout | 60000 | Time, in milliseconds, before an old container is automatically killed. Only used with the hand-over update strategy. |
v7.23.0 | v2.21.0 |
* balenaOS versions that ship with a compatible device supervisor version as per balenaOS Changelog.
These labels are applied to a specific service with the labels: setting:
labels:
io.balena.features.balena-socket: '1'
io.balena.features.kernel-modules: '1'
io.balena.features.firmware: '1'
io.balena.features.dbus: '1'
io.balena.features.sysfs: '1'
io.balena.features.procfs: '1'
io.balena.features.journal-logs: '1'
io.balena.features.supervisor-api: '1'
io.balena.features.balena-api: '1'
io.balena.update.strategy: download-then-kill
io.balena.update.handover-timeout: ''