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
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
expose	Informational only. Removed to prevent conflicts with other network configurations
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

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.extra-firmware	false	Enables the service to provide extra firmware files to the host OS. Use this with the extra firmware block to add Linux firmware without depending on an OS release.	v17.5.2	v6.10.7
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: ''