Skip to main content
Version: V3.2

Capture Edge on Balena

This guide describes the general workflow for running Capture Edge on an edge device managed with Balena. This documentation is targeted at machine builders and integrators who ship machines with a pre-configured edge device on board.

The steps here are device-agnostic: they apply to any board that balenaOS supports. Anything that is specific to a particular board (how to flash it, which peripherals need extra configuration) lives in the manufacturer's documentation.

How it fits together​

  • balenaOS runs on the device and connects it to a fleet in balenaCloud (or your own openBalena instance).
  • Capture Edge is deployed to that fleet as a multi-container release described by a docker-compose.yml.
  • Every device provisioned into the fleet automatically downloads and runs the release, and can be updated and monitored remotely.

New to Balena? Start with the Balena getting-started guide for your board, then come back here for the Capture-specific parts.

Choosing your Balena setup​

Capture Edge on Balena can run under either of two setups. The flashing and configuration steps are identical; only where you log in, download the OS image, and deploy the release differs.

  • Option A: Your own Balena instance. You own the balenaCloud (or openBalena) account and create the fleet yourself. You download OS images and push Capture releases from your own instance.
  • Option B: Vintecc's Balena instance. Vintecc onboards you with an account that has access to only your own fleet(s). You log in to Vintecc's balenaCloud, download OS images from the fleet prepared for you, and, depending on your access level, either push releases yourself or have Vintecc deploy them.

Both options require pull access to Vintecc's image registry (harbor.mgmt.vintecc.cloud); Vintecc provides the credentials. Wherever this guide says "balenaCloud" or "your fleet," use whichever instance applies to you.

Prerequisites​

  • A balenaOS-supported device. Check the supported devices list. If your board is not listed, see If your device isn't supported.
  • Access to a balenaCloud fleet (your own, or one Vintecc prepares for you).
  • balenaEtcher (or another flashing tool) on your workstation.
  • The balena CLI, installed and logged in (balena login, pointed at the correct instance), if you will push the Capture release yourself.
  • The registry secrets file (registry-secrets.yml) with credentials for harbor.mgmt.vintecc.cloud, provided by Vintecc (needed if you push releases yourself).

1. Create or select your fleet​

In balenaCloud, create a fleet (or open the one prepared for you) and select the device type that matches your hardware. The device type determines the CPU architecture the release is built for, so it must match your board.

For advanced info on fleets, see the Balena Fleet Management Masterclass in the Balena docs.

2. Flash balenaOS onto the device​

  1. In your fleet, choose Add device and download a configured balenaOS image. This image embeds the network and fleet credentials, so the device joins your fleet on first boot. Choose a production image for shipped machines.
  2. Write the image to the device's boot media with balenaEtcher.
  3. Boot the device with a network connection. After a minute or two it should appear online in your fleet.

The exact flashing procedure depends on the board: SD card, USB, internal eMMC, or a compute module that must be put into a programming/mass-storage mode first. Follow:

  • the Balena getting-started guide for your specific device (index here), and
  • the manufacturer's flashing instructions, and
  • the matching device-specific Capture guide if one exists. Vintecc will provide this upon request.

3. Device-specific configuration (optional)​

Some boards need extra low-level configuration to enable peripherals (RTC, status LEDs, ADCs, serial interfaces, and so on). On a Raspberry Pi-based device this lives in config.txt; other device types use an equivalent mechanism. There are two ways to apply it:

  • Before first boot: mount the flashed boot partition (label resin-boot / balena-boot) and edit config.txt directly. Any values you add are imported into balenaCloud when the device provisions.
  • After provisioning (recommended for fleets): set the equivalent BALENA_HOST_CONFIG_* configuration variables on the fleet or device in the balenaCloud dashboard. For example, dtoverlay and dtparam are set via BALENA_HOST_CONFIG_dtoverlay / BALENA_HOST_CONFIG_dtparam, using a comma-separated list of quoted values for multiple entries. Applying these reboots the device.

References: Advanced boot settings and Configuration variables.

The exact overlays/parameters for your board are documented in the manufacturer's material and in the device-specific Capture guide.

4. Deploy the Capture Edge stack​

Capture Edge runs as a multi-container release. The file below is the standard Capture Edge on Docker setup with a few Balena-specific adjustments:

  • Image tags are pinned explicitly. Balena does not perform the ${CAPTURE_DOCKER_TAG:-latest} environment-variable substitution the standard file relies on, so each Capture component is pinned to a fixed version, 2.2.6 at the time of writing. Update these tags when Vintecc confirms a newer version.
  • Services talk to each other by service name. Balena resolves containers by their compose service name (e.g. influxdb), so no container_name entries are needed.

docker-compose.yml (Balena)​

version: "2"

services:
  # Capture Stack
  cloudmanager:
    image: harbor.mgmt.vintecc.cloud/capture-edge/cloudmanager:2.2.6
    ports:
      - "5004:5004"
      # - '80:5004' # Use this instead of the above line if you want to access the cloudmanager on port 80. Useful for Balena's public URL feature.
    volumes:
      - capture_etc:/etc/capture
    environment:
      IS_RUNNING_IN_DOCKER: "true"
      # CAPTURE_SERVER_BASE_URL: https://portal.captureplatform.com # Point the device at another Capture server. Default: https://portal.captureplatform.com
      # CAPTURE_COMPANY: Vintecc # Company the device is provisioned under. Default: Vintecc
    restart: unless-stopped

  syncer:
    image: harbor.mgmt.vintecc.cloud/capture-edge/syncer:2.2.6
    ports:
      - "5001:5001"
    volumes:
      - capture_etc:/etc/capture
    environment:
      IS_RUNNING_IN_DOCKER: "true"
    depends_on:
      - cloudmanager
    restart: unless-stopped

  collector:
    image: harbor.mgmt.vintecc.cloud/capture-edge/collector:2.2.6
    ports:
      - "5002:5002"
      # - "4840:4840"   # OPC UA server
      # - "48898:48898" # ADS / TwinCAT
    volumes:
      - capture_etc:/etc/capture
    environment:
      IS_RUNNING_IN_DOCKER: "true"
    depends_on:
      - cloudmanager
    restart: unless-stopped

  analytics:
    image: harbor.mgmt.vintecc.cloud/capture-edge/analytics:2.2.6
    ports:
      - "5003:5003"
    volumes:
      - capture_etc:/etc/capture
    environment:
      IS_RUNNING_IN_DOCKER: "true"
    depends_on:
      - cloudmanager
    restart: unless-stopped

  # Storage
  influxdb:
    image: harbor.mgmt.vintecc.cloud/vintecc/influxdb1:latest
    privileged: true
    ports:
      - "8086:8086"
      - "8088:8088"
    volumes:
      - influxdb_config:/etc/influxdb/
    restart: unless-stopped

volumes:
  capture_etc:
  influxdb_config:

Registry access (registry secrets)​

The Capture images live in Vintecc's private registry (harbor.mgmt.vintecc.cloud). When you push a release, the Balena builder needs credentials to pull them. You supply these with a registry secrets file passed to balena push. The credentials are used by the builder at build time only; devices then pull the images from the balenaCloud registry.

Create a file named registry-secrets.yml next to your docker-compose.yml:

'harbor.mgmt.vintecc.cloud':
  username: <username>
  password: <password>

Vintecc provides the username and password. See Balena's private base images documentation for details.

caution

Keep this file private, do not commit it to source control (add it to .gitignore).

Pushing the release​

Save the compose file above as docker-compose.yml in an empty directory, put registry-secrets.yml next to it, and push from that directory:

balena push <your-fleet-slug> --registry-secrets ./registry-secrets.yml

Every device in the fleet then downloads and runs the release automatically. For the full deployment workflow (including balena deploy for CI/CD pipelines), see Deploy to your fleet.

Optional CAN bus support

If the machine uses CAN, additional settings are required (privileged, network_mode: host, and COLLECTOR_URL / CLOUDMANAGER_URL). Contact Vintecc for the CAN-enabled variant of this file.

5. Configure and provision Capture Edge​

  1. Once the release is running, open the cloudmanager UI at http://<device-ip>:5004/. You can find the device's IP in the balenaCloud dashboard, or expose the UI over the device public URL (which uses port 80, see the commented port mapping in the compose file).
  2. Configure the database connection. Because the containers run on a Docker network, set Capture's local database address to the influxdb service name rather than 127.0.0.1, as described in Configuring Capture Edge with Docker networking.
  3. The device provisions itself against the Capture server on first run. To place it under a specific company or server automatically at scale, uncomment and set CAPTURE_COMPANY and CAPTURE_SERVER_BASE_URL on the cloudmanager service before pushing. Alternatively, change the Company in the Edge UI after the first boot and restart the cloudmanager service.

6. Verify​

  • The device shows online in balenaCloud with all services running.
  • The cloudmanager UI loads at http://<device-ip>:5004/.
  • Any device-specific peripherals (RTC, LEDs, I/O) behave as expected.
  • Data appears in the Capture portal for the device once a configuration has been pushed to it.

Accessing the device​

Balena provides several ways to reach a running device for diagnostics:

  • Dashboard: logs, terminal, and device actions from balenaCloud.
  • SSH: balena device ssh <uuid> <service> over the balena VPN. See the CLI documentation.
  • Local mode: build and push directly to a development device on your LAN. See Develop locally.
  • Public URL: expose the device's port 80 as a public web URL from the dashboard. See Actions and settings.

If your device isn't supported​

If your board is not on the supported devices list, you may be able to boot it with a similar device type and enable missing peripherals with a device tree overlay, or request Balena's Custom Device Support service. Talk to your Vintecc representative before committing to unsupported hardware for a production machine.

Capture

Balena

For fleet access, registry credentials, CAN bus support, device-specific guides, or version updates, contact your Vintecc representative.