obcommunity/open-balena-builder repository overview

⁠Build Server for Open Balena

Open source build server for openbalena⁠, a platform to deploy and manage connected devices.

⁠Features

The goal of this project is to faciliate push builds, which allow for significant performance enhancement by utilizing remote docker servers. On its own, open-balena only supports deployment of applications using balena deploy, which runs builds on a local machine. This project also facilitates the usage of both amd and arm architecture build servers, further enhancing performance by running native builds. This project also integrates with open-balena-delta, allowing for the generation of delta images at the time of build, making the device update process much faster as devices do not wait for delta updates to be created.

⁠Compatibility

This project is compatible with open-balena and specifically relies on the open-balena-api and open-balena-registry components. This project is also compatible with open-balena-delta for creating delta updates.

⁠Installation

open-balena-builder is meant to be installed as part of open-balena, and ideally at the same time. For thoes running open-balena on k8s, we have included services to build it in the open-balena helm project⁠. If you are running open-balena via docker-compose, you will need to modify the scripts to mirror the setup in the helm charts or recreate it using the configuration steps below.

To configure open-balena-builder you must define four environment variables and two volumes for the container:

Environment Variables:

• BALENA_TLD: open-balena base hostname i.e. openbalena.<yourdomain.com>
• API_HOST: open-balena-api hostmame, i.e. api.openbalena.<yourdomain.com>
• DELTA_HOST: open-balena-delta hostmame, i.e. delta.openbalena.<yourdomain.com>. Note that this is an optional variable, and if omitted, delta updates will not be generated
• DOCKER_HOST_AMD64: The hostname of your AMD64 architeture docker server, in the format: tcp://:2375 (This address needs to be accessible from open-balena-builder)
• DOCKER_HOST_ARM64: The hostname of your ARM64 architeture docker server, in the format: tcp://:2375 (This address needs to be accessible from open-balena-builder)
• DOCKER_BUILDKIT: You likely want to set this to "0"
• TOKEN_AUTH_BUILDER_TOKEN: The master builder token which was generated by the qucikstart script when you installed open-balena

Note that you can omit one of the AMD64 or ARM64 docker host variables, just not both, as open-balena-builder needs at least one docker host to run builds.

Setting up the docker hosts is outside the scope of this project, however if you utilize the helm scripts linked above for installation, you will be provided with templates for these.

Hostnames:

You will also need to set up a new hostname for your open-balena-builder instance, which likely will just be mapped to your open-balena haproxy instance, assuming you used the helm script or otherwise integrated it with your docker-compose scripts.

• builder.<yourdomain.com>: IP address / hostname of open-balena-haproxy

Delta Updates:

To enable delta updates, follow the installation and configuration instructions in the open-balena-delta⁠ repo.

⁠Usage

Once installed, you can utilize the builder via balena-cli by running balena push <fleet name> - and watch it build / deploy remotely!

⁠Limitations and Known Issues

• Likely many; needs more testing to cover off corner cases

⁠Credits

• This would not be possible without the great work by the Balena team in developing balena-cli⁠, the versatile command line tool used to manage all aspects of balena