TODO for full user application support

[pipex]

Compose spec coverage

This includes runtime only configurations, build and develop are out of scope. See the Compose specification for further info

Top-level networks

• driver
• driver_opts
• enable_ipv6
• internal
• ipam (with driver, config[].subnet|gateway|ip_range|aux_addresses, options)
• labels (map and key=value list form)

Missing:

• enable_ipv4 — modeled implicitly today (the engine sets it via com.docker.network.enable_ipv4 driver_opt, which helios strips on read); the explicit top-level field is not deserialized. The support of this property depends on the engine version and probably requires use of contracts.

Won't support

• name — explicit name override. Not supported as namespacing is controlled by helios to avoid clashing.
• external — declare a network that helios should not create/destroy. This can cause racing issues as the network needs to be created by an external process before helios can install the composition.

Top-level volumes

Implemented in helios-remote-model::Volume:

• driver
• driver_opts
• labels

Won't support

• name — explicit name override. Not supported as namespacing is controlled by helios to avoid clashing.
• external — declare a volume that helios should not create/destroy. This can cause racing issues as the volume needs to be created by an external process before helios can install the composition.

Services — top-level fields

• image
• labels
• environment (map and list form; values typed as string / bool / int / float)
• command (string with shell-style splitting, or list)
• restart (no, always, on-failure[:N], unless-stopped; defaults to always)
• healthcheck (bare string, CMD/CMD-SHELL/NONE list, disable: true shorthand; per-field tracking via LABEL_CONFIG_HEALTHCHECK so the engine doesn't bleed image defaults into the round-trip)
• networks (see per-endpoint section below)
• network_mode — none, host, bridge. service:<name> blocked on depends_on; container:<name> rejected.
• volumes (see mount section below)
• cgroup (host / private)
• cgroup_parent
• cpuset
• cpu_rt_period
• cpu_rt_runtime
• cpu_shares
• cpus (fractional, validated finite/non-negative and bounded by i64 nano_cpus)
• domainname
• hostname
• init
• mem_limit
• mem_reservation
• oom_score_adj
• pids_limit
• privileged
• read_only
• runtime
• shm_size
• stop_grace_period
• stop_signal
• tty
• user
• userns_mode
• uts
• working_dir

Lifecycle / ordering:

• depends_on — also unblocks network_mode: service:<name> and per-network service: references.
• post_start, pre_stop (lifecycle hooks). These probably won't be part of the initial release. These seem to be very specific to CLI usage of compose and is not evident how to handle failures on an automated deployment system, that needs additional discussion. Even podman compose doesn't implement these hooks
• entrypoint.

Networking:

• ports.
• extra_hosts.
• dns, dns_opt, dns_search.
• mac_address (top-level / default-network form — per-network is done). According to the spec, this configuration might get rejected by docker engine >= 25, so we'll probably need some contract support for this

Namespaces:

• ipc (service:<name> requires depends_on, container:$NAME will not be supported).
• pid (service:<name> requires depends_on, container:$NAME will not be supported).

Security / capabilities:

• cap_add, cap_drop.
• security_opt (label= and apparmor= require OS support, won't be supported, for seccomp=, only seccomp=unconfined will be supported)
• sysctls.
• group_add.

Devices / kernel:

• devices (CDI syntax won't be supported)
• device_cgroup_rules.
• ulimits.
• annotations (OCI runtime annotations. Requires contract support as these are only available from Docker v24 and above).

Mounts shortcut:

• tmpfs (top-level shortcut). The long-form { type: tmpfs, ... } entry inside volumes already works; what's missing is the tmpfs: [/run, /tmp] field.

Composition references:

• secrets (mount declared secrets into the service). This won't be part of the initial release as it requires design to work with the top levels secrets configuration
• use_api_socket — tightly coupled to the bind allowlist; equivalent to io.balena.features.balena-socket

Out of scope (not part of the device-side target state — resolved by the backend or the CLI before delivery): extends, profiles, env_file, label_file, pull_policy, attach, models, provider, scale, deploy.

Won't support

• cpu_count, cpu_percent, isolation, credential_spec, links, external_links, volumes_from (Windows-only or deprecated).
• platform (would need multi-arch image resolution).
• logging (logging is managed by the host OS).
• container_name containers are namespaced by helios to avoid clashing
• configs (mount declared configs into the service). It is not compatible with separate build and runtime environments
• expose, is a documentation only property
• stdin_open, meant for interactive sessions, not relevant for remote deployment
• mem_swappiness, memswap_limit, there is no swap management interface on balenaOS
• cpu_period, cpu_quota, related to CFS which is no longer available in newer kernels
• blkio_config, not portable, since block device names may differ between devices in a fleet
• gpus, equivalent to device deploy request
• storage_opt, requires xfs enabled kernel which balenaOS doesn't include
• oom_kill_disable, not supported with cgroups v2 (source)

Services — per-endpoint networks.<name>

• aliases
• ipv4_address
• ipv6_address
• link_local_ips
• mac_address
• driver_opts
• gw_priority
• priority

Missing:

• interface_name (recent spec addition).
• service:<network> form — blocked on depends_on.

Services — volumes mount entries

• volume (short src:dst[:ro|rw|z|Z], and long form with volume.nocopy, volume.subpath, read_only)
• bind (short and long form; bind.propagation, bind.create_host_path, read_only)
• tmpfs (long form with tmpfs.size, tmpfs.mode)

Pending:

• image, depends on the engine version, needs contract support

Rejected by design: npipe, cluster.

Notes / current restrictions:

• Bind mount sources are restricted to a fixed allowlist (/var/run/docker.sock, /run/dbus, /sys, /proc, /lib/modules, /lib/firmware, /var/log/journal, /run/log/journal, /etc/machine-id).
• Short-form SELinux flags z/Z are accepted but ignored (no SELinux enforcement assumed on the device).
• Mounts are canonicalized by target on deserialization so reorderings in the remote composition don't propagate downstream.

Other features

• update locks
• contracts / container requirements - initial work here
• API
• feature labels (depends on volumes)
• update strategies