balenify

Balenify — Convert Docker Projects to balenaCloud

What This Skill Covers

This skill covers the full workflow for converting a standard Docker or docker-compose project to run on balenaCloud. That includes Dockerfile templates for multi-architecture builds, volume mount conversion, networking differences, environment variable handling, hardware access, docker-compose.yml adaptations, and balena.yml fleet metadata.

Use this as a reference whenever you're porting an existing project to balena or building a new balena fleet from scratch.

Balenify Checklist

Quick reference for the conversion steps:

• Replace host bind mounts (./data:/app) with named volumes
• Remove .env files — use dashboard/CLI variables instead
• Add balena.yml with fleet name and supported device types
• Convert Dockerfiles to .template if arch-specific base images are needed
• Add balena-specific labels for hardware features (D-Bus, kernel modules, supervisor API)
• Set privileged: true or selective devices:/cap_add: for hardware access
• Set network_mode: host if the service needs host networking (multicontainer defaults to bridge)
• Remove links: — bridge network provides service discovery by container name
• Pin version: "2.1" in docker-compose.yml (balena uses Compose v2/2.1)

Dockerfile Templates

Balena's build system supports Dockerfile templates — files named Dockerfile.template that undergo variable substitution before Docker processes them. The template system exists because Docker images are architecture-specific, and balena fleets often span multiple device types (e.g., Raspberry Pi 3, Pi 4, Intel NUC) with different CPU architectures.

Core Concept: Template Variable Substitution

Template variables use %%VARIABLE%% syntax. The balena builder replaces them with fleet/device-specific values before the Docker build begins — Docker never sees the %% tokens.

Available Variables

Variable	Description	Example Value
%%BALENA_ARCH%%	Target CPU architecture	aarch64, amd64, armv7hf
%%BALENA_MACHINE_NAME%%	Yocto machine name for the device type	raspberrypi4-64, genericx86-64-ext
%%BALENA_APP_NAME%%	Fleet name	my-fleet
%%BALENA_RELEASE_HASH%%	Release hash	abc123...
%%BALENA_SERVICE_NAME%%	Service name from docker-compose.yml	pihole

Use %%BALENA_ARCH%% by default. Only use %%BALENA_MACHINE_NAME%% when you genuinely need device-type-specific behavior (rare). Machine name won't evaluate correctly if a fleet has mixed device types.

Dockerfile Resolution Order

The balena builder picks the first match from this priority list:

1. Dockerfile.<device-type> — exact device type match (e.g., Dockerfile.raspberrypi4-64)
2. Dockerfile.<arch> — architecture match (e.g., Dockerfile.aarch64)
3. Dockerfile.template — universal fallback with variable substitution
4. Dockerfile — plain Dockerfile, no substitution

This applies during balena push, balena build, balena deploy, and git push.

When to use templates vs plain Dockerfiles:

• If your base image is multi-platform (published with Docker manifest lists) or you only target one architecture → use a plain Dockerfile
• If you need to select between architecture-specific images that lack multi-platform manifests → use Dockerfile.template
• Most services in a fleet can use plain Dockerfiles. Only the ones pulling arch-specific images need templates.

Balena Arch vs Docker/Go Arch

Balena has its own architecture naming convention, distinct from Docker and Go:

Balena (%%BALENA_ARCH%%)	Docker Platform	Go GOARCH
aarch64	linux/arm64	arm64
amd64	linux/amd64	amd64
armv7hf	linux/arm/v7	arm (GOARM=7)
rpi	linux/arm/v6	arm (GOARM=6)
i386	linux/386	386

This matters because balenaCloud doesn't support multi-arch fleets yet — each fleet targets a single device type and architecture. Fleets and blocks on balena hub (bh.cr) are typically published as separate images per balena arch (e.g., my-block-aarch64, my-block-amd64), not as multi-platform manifests. Templates with %%BALENA_ARCH%% map directly to these naming conventions.

The Simple Pattern (Use This by Default)

For most cases, a single FROM line with %%BALENA_ARCH%% interpolated into the image reference is all you need:

FROM bh.cr/some-org/my-block-%%BALENA_ARCH%%/1.0.0

Or with a standard registry:

FROM myregistry/myimage-%%BALENA_ARCH%%:1.0.0

COPY . /app
CMD ["/app/start.sh"]

This pattern works especially well with bh.cr, where blocks and fleets are published per-architecture using balena's naming convention. The builder substitutes %%BALENA_ARCH%% → aarch64 (or amd64, armv7hf, etc.) and Docker pulls the right image.

Multi-Stage Pattern

Use this when the simple pattern won't work. The two main reasons:

1. Arch naming mismatch: The upstream image uses Docker/Go arch names (arm64, arm64v8) instead of balena names (aarch64, armv7hf). A simple FROM image-%%BALENA_ARCH%%:tag would try to pull image-aarch64:tag which doesn't exist.
2. Renovate/Dependabot pinning: You want automated dependency tooling to independently update per-arch image references. The simple %%BALENA_ARCH%% pattern embeds a variable inside the image reference, which Renovate can't parse.

ARG BALENA_ARCH=%%BALENA_ARCH%%

# Stage names use balena arch convention — map to whatever the upstream publishes
FROM linuxserver/wireguard:amd64-latest AS wireguard-amd64
FROM linuxserver/wireguard:arm64v8-latest AS wireguard-aarch64

# hadolint ignore=DL3006
FROM wireguard-${BALENA_ARCH}

The key trick: name each stage with the balena arch suffix (e.g., wireguard-aarch64) regardless of what the upstream tag calls it (e.g., arm64v8-latest). Then FROM wireguard-${BALENA_ARCH} resolves correctly.

How it works:

1. %%BALENA_ARCH%% is substituted by the balena builder before Docker runs
2. Docker ARG captures the resolved value
3. Named FROM stages alias each upstream image to balena arch names
4. FROM wireguard-${BALENA_ARCH} resolves to the correct stage
5. Docker only pulls the selected stage — the others are skipped

The # hadolint ignore=DL3006 comment suppresses the "always tag the version of an image explicitly" lint warning on the dynamic FROM line.

Supported Architecture Values

%%BALENA_ARCH%%	Devices
aarch64	Raspberry Pi 3/4/5 (64-bit), Jetson, most modern ARM boards
armv7hf	Raspberry Pi 2/3 (32-bit), BeagleBone
amd64	Intel NUC, generic x86_64
rpi	Raspberry Pi 1 / Zero (armv6)

Volume Mounts

Host bind mounts (./data:/app/data) do not work on balena. The host filesystem layout is managed by balenaOS and is not directly accessible to containers.

Use Named Volumes

Declare volumes in the top-level volumes: section and reference them in services:

version: "2.1"

volumes:
  app-data:
  config:

services:
  my-service:
    build: my-service
    volumes:
      - app-data:/app/data
      - config:/etc/myapp

Key behaviors

• Named volumes persist across container updates as long as the volume name stays the same
• Shared volumes between services: mount the same named volume in multiple services for inter-service data exchange
• Host OS path: /var/lib/docker/volumes/<APP_ID>_<volume_name>/_data
• Single-container apps get a default resin-data volume mounted at /data — no explicit volume config needed
• Warning: volumes are purged if a device is moved to a different fleet

Converting bind mounts

Docker (original)	Balena (converted)
./data:/app/data	app-data:/app/data (+ declare app-data: in volumes:)
./config.json:/etc/app/config.json	Bake into image with COPY, or use an env var
/var/run/docker.sock:/var/run/docker.sock	Use io.balena.features.balena-socket: 1 label instead

Networking

Single-container apps

Host networking by default — the container shares the host's network stack. No port mapping needed.

Multicontainer apps

Bridge network by default — each service gets its own network namespace. Services are routable by container name.

services:
  frontend:
    build: frontend
    ports:
      - "80:3000"   # expose to host/external network

  backend:
    build: backend
    # no ports needed — frontend reaches backend at http://backend:8080

Key points

• ports: only needed to expose a service to the host network or external clients — not for inter-service communication
• No need for links: — the bridge network provides automatic service discovery by container name
• Set network_mode: host on a service if it needs direct access to the host network stack (e.g., mDNS, DHCP, network scanning)
• Custom networks (networks:) are not supported — all multicontainer services share a single bridge network

Environment Variables

No .env files

Balena does not read .env files. Instead, set variables through:

• balenaCloud dashboard → fleet or device variables (with optional per-service scope)
• CLI: balena env set MY_VAR my_value --fleet my-fleet or --device <uuid>

Variable priority (highest to lowest)

1. Device + service variable
2. Device variable
3. Fleet + service variable
4. Fleet variable

Balena-injected variables

These are automatically available in every container:

Variable	Value
BALENA	1 (use to detect running on balena)
BALENA_DEVICE_UUID	Device UUID
BALENA_APP_ID	Fleet/application numeric ID
BALENA_APP_NAME	Fleet name
BALENA_SERVICE_NAME	Service name from docker-compose.yml
BALENA_SUPERVISOR_ADDRESS	Supervisor API URL (usually http://127.0.0.1:48484)
BALENA_SUPERVISOR_API_KEY	API key for supervisor requests

Values can be up to 1MB each.

Converting from .env files

# Read each KEY=VALUE from .env and set as fleet variables
while IFS='=' read -r key value; do
  [[ "$key" =~ ^#.*$ || -z "$key" ]] && continue
  balena env set "$key" "$value" --fleet my-fleet
done < .env

Hardware Access

Single-container apps

Privileged by default — full access to /dev and all host devices. No extra config needed.

Multicontainer apps

Not privileged by default. You must explicitly grant access:

Option 1 — Full privileged mode:

services:
  my-service:
    build: my-service
    privileged: true

Option 2 — Selective access (preferred when possible):

services:
  my-service:
    build: my-service
    devices:
      - "/dev/i2c-1:/dev/i2c-1"
      - "/dev/ttyUSB0:/dev/ttyUSB0"
    cap_add:
      - SYS_RAWIO

Balena feature labels for hardware

Use labels instead of manual /dev paths where possible — they're more stable across device types:

Label	Grants access to
io.balena.features.kernel-modules: 1	Kernel module loading
io.balena.features.dbus: 1	Host D-Bus socket
io.balena.features.supervisor-api: 1	Supervisor REST API
io.balena.features.balena-api: 1	balenaCloud API
io.balena.features.balena-socket: 1	balenaEngine socket (like Docker socket)
io.balena.features.sysfs: 1	Host /sys filesystem
io.balena.features.procfs: 1	Host /proc filesystem
io.balena.features.gpu: 1	GPU device access

Prefer feature labels over raw device paths — they abstract hardware differences across device types.

docker-compose.yml for Balena

Balena uses Docker Compose v2/2.1. Each service with a build: directive points to a directory containing a Dockerfile (or Dockerfile.template).

version: "2.1"

services:
  my-service:
    build: my-service
    network_mode: host
    cap_add:
      - NET_ADMIN
    labels:
      io.balena.features.kernel-modules: 1
    tmpfs:
      - /tmp
      - /var/run

  # Services using pre-built images don't need templates
  helper:
    image: bh.cr/some-org/some-block/1.0.0
    restart: no

Balena-Specific Labels

Label	Purpose
io.balena.features.kernel-modules: 1	Access kernel modules
io.balena.features.dbus: 1	Access host D-Bus
io.balena.features.supervisor-api: 1	Access supervisor API
io.balena.features.balena-api: 1	Access balena API
io.balena.features.balena-socket: 1	Access balenaEngine socket
io.balena.features.sysfs: 1	Access host /sys
io.balena.features.procfs: 1	Access host /proc
io.balena.features.gpu: 1	GPU device access

Update Strategy Labels

Control how balena updates containers:

Label	Values	Default
io.balena.update.strategy	download-then-kill, kill-then-download, delete-then-download, hand-over	download-then-kill
io.balena.update.handover-timeout	Seconds (for hand-over strategy)	60

• download-then-kill — download new image, then stop old container (minimal downtime, needs 2x storage)
• kill-then-download — stop old container first, then download (saves storage, longer downtime)
• delete-then-download — delete old image and container, then download (maximum storage savings)
• hand-over — old and new containers run simultaneously during handover period (zero-downtime deploys)

balena.yml

Every fleet project has a balena.yml at root:

name: "My Fleet"
type: "sw.application"
version: 1.0.0
description: "What this fleet does"
data:
  defaultDeviceType: "raspberrypi4-64"
  supportedDeviceTypes:
    - "raspberrypi3-64"
    - "raspberrypi4-64"
    - "genericx86-64-ext"

The supportedDeviceTypes list determines which architectures your Dockerfile.template must handle.

Debugging Build Failures

Symptom	Likely Cause
invalid reference format	Template variable not substituted — check file is named .template
manifest unknown	Architecture not published for that image tag
no match for platform	Using a plain Dockerfile where a template is needed
Wrong arch binary runs	%%BALENA_MACHINE_NAME%% resolved to fleet default, not target device

Common Patterns Reference

Read references/patterns.md for:

• Legacy %%RESIN_MACHINE_NAME%% syntax (pre-2019 projects)
• Balenalib base images (FROM balenalib/%%BALENA_MACHINE_NAME%%-alpine)
• install_packages helper in balenalib images
• Cross-compilation with TARGETARCH fallback
• The INITSYSTEM on ENV (legacy balena supervisor integration)
• bh.cr (balena hub container registry) image references
• Renovate configuration patterns for auto-updating image tags

Workflow

When converting a Docker project to balena:

1. Check balena.yml → what device types does this fleet target?
2. Map device types to architectures (see table above)
3. For each service: does its base image support multi-platform? If yes → plain Dockerfile. If no → Dockerfile.template with the simple %%BALENA_ARCH%% pattern.
4. Replace bind mounts with named volumes.
5. Remove .env files — migrate variables to balenaCloud dashboard or CLI.
6. Add balena-specific labels for hardware features the service needs.
7. Set privileged: true or selective devices:/cap_add: for hardware access.
8. Test with balena build --deviceType <type> for each target.