balenaSupervisor

balenaSupervisor is balena's on-device agent, responsible for monitoring and applying changes to an IoT device. It communicates with balenaCloud and handles the lifecycle of an IoT application.

Using the balenaEngine's (our IoT-centric container engine) remote API, balenaSupervisor will install, start, stop and monitor IoT applications, delivered and ran as OCI compliant containers.

balenaSupervisor is developed using Node.js.

Contributing

If you're interested in contributing, that's awesome!

Contributions are not only pull requests! Bug reports and feature requests are also extremely value additions.

Issues

Feature request and bug reports should be submitted via issues. One of the balenaSupervisor team will reply and work with the community to plan a route forward. Although we may never implement the feature, taking the time to let us know what you as a user would like to see really helps our decision making processes!

Pull requests

Here's a few guidelines to make the process easier for everyone involved.

• Every PR should have an associated issue, and the PR's opening comment should say "Fixes #issue" or "Closes #issue".
• We use Versionist to manage versioning (and in particular, semantic versioning) and generate the changelog for this project.
• At least one commit in a PR should have a Change-Type: type footer, where type can be patch, minor or major. The subject of this commit will be added to the changelog.
• Commits should be squashed as much as makes sense.
• Commits should be signed-off (git commit -s)

Developing the supervisor

Requirements

These are the system requirements for developing and testing the balenaSupervisor on a local machine

• Node.js v20 or latest
• Rust v1.64 or latest for installing the @balena/systemd NPM package.
• If developing on an architecture not supported by default by node-sqlite3, a C++ compiler and linker are also required, plus the libsqlite development headers.

Setup

To get the codebase setup on your development machine follow these steps. For running the supervisor on a device see Developing the supervisor or Using balenaOS-in-container.

# Clone the repo
git clone git@github.com:balena-os/balena-supervisor.git

# Install dependencies
npm ci

We explicitly use npm ci over npm install to ensure the correct package versions are installed. More documentation for this can be found here on the npm cli docs.

You're now ready to start developing.

Running your code

By far the most convenient way to test your supervisor code is to download a development image of balenaOS from the dashboard, and run it on a device you have to hand. You can then use the local network to sync changes using livepush and npm run sync.

If you do not have a device available, it's possible to run a supervisor locally, using balenaOS-in-container. These steps are detailed below.

Sync

Example:

# Replace amd64 with your device architecture
$ npm run sync -- d19baeb.local -a amd64

> balena-supervisor@10.11.3 sync /home/cameron/Balena/modules/balena-supervisor
> ts-node --project tsconfig.json sync/sync.ts "d19baeb.local"

Step 1/23 : ARG ARCH=amd64
Step 2/23 : ARG NODE_VERSION=10.19.0
Step 3/23 : FROM balenalib/$ARCH-alpine-supervisor-base:3.11 as BUILD
...

Note: For .local resolution to work you must have installed and enabled MDNS. Alternatively you can use the device's local IP.

Sync will first run a new build on the target device (or balenaOS container), after livepush has processed the livepush specific commands and will start the new supervisor image on device.

The supervisor logs are then streamed back from the device, and livepush will then watch for changes on the local FS, and sync any relevant file changes to the running supervisor container. It will then decide if the container should be restarted, or let nodemon handle the changes.

Using balenaOS-in-container

This process will allow you to run a development instance of the supervisor on your local computer. It is not recommended for production scenarios, but allows someone developing on the supervisor to test changes quickly. The supervisor is run inside a balenaOS instance running in a container, so effectively it's a Docker-in-Docker instance (or more precisely, balenaEngine-in-Docker).

To run the supervisor in a balenaOS-in-container instance, first follow the installation instructions on the balenaOS-in-container repository. Make sure you have the image configured in development mode. After the image starts you should be able to use the sync method described above for running a livepush Supervisor on the docker container.

# Replace d19baeb.local with the container address.
$ npm run sync -- d19baeb.local -a amd64

> balena-supervisor@10.11.3 sync /home/cameron/Balena/modules/balena-supervisor
> ts-node --project tsconfig.json sync/sync.ts "d19baeb.local"

Developing using a production image or device

A production balena image does not have an open docker socket, required for livepush to work. In this situation, balena tunnel can be used to tunnel the necessary ports to the local development machine.

For a balena device on a different network:

# Open tunnel using the device uuid
balena tunnel <uuid> -p 22222
# Tunnel device ports to the local machine
ssh -ACN -p 22222 \
-L 2375:/var/run/balena-engine.sock \
-L 48484:127.0.0.1:48484 \
root@localhost
# On another terminal
npm run sync -- 127.0.0.1 -a amd64

For a balena device on the local network, the balena tunnel step is not necessary.

# Tunnel device ports to the local machine
# replace d19baeb.local below with the local network address
# of the balena device
ssh -ACN -p 22222 \
-L 2375:/var/run/balena-engine.sock \
-L 48484:127.0.0.1:48484 \
-L 22222:127.0.0.1:22222 \
root@d19baeb.local
# On another terminal
npm run sync -- 127.0.0.1 -a amd64

Building

The supervisor is built automatically by the CI system, but a docker image can be also be built locally using the balena CLI.

To build a docker image for amd64 targets, it's as simple as:

balena build -d genericx86-64-ext -A amd64

For other architectures, the argument to -A must be replaced with the proper architecture and the correct device type must be passed using -d.

Available architectures: amd64, i386, aarch64, armv7hf and rpi

For instance to build for raspberrypi4:

balena build -d raspberrypi4-64 -A aarch64

Testing

The codebase splits the test suite into unit and integration tests. While unit tests can be run in the local development machine, integration tests require a containerized environment with the right dependencies to be setup.

To run type checks, and unit tests, you can use:

npm run test

The supervisor runs on Node v20, so using that specific version will ensure tests run in the same environment as production.

In order to run all tests, unit and integration, docker-compose is required. The following command will build the image for an amd64 target (running test during the build) and setup the necessary dependencies for running integration tests.

npm run test:compose

This is the same process that happens in the Supervisor repository CI system, to ensure released supervisor versions have been properly tested.

Alternatively, you can launch a test environment using the following commands.

# Launch the environment
npm run test:env

And then run all tests using

npm run test:node

For more information about testing the Supervisor, see the testing README.

Running specific tests quickly

You can run specific tests quickly with the test:unit script or the test:integration script (if working in a test environment) by matching with test suites (describe) or test cases (it) using a string or regexp:

npm run test:unit -- -g "JSON utils"

npm run test:unit -- -g "detect a V2 delta"

npm run test:unit -- -g "(GET|POST|PUT|DELETE)"

The --grep option, when specified, will trigger mocha to only run tests matching the given pattern which is internally compiled to a RegExp.

Downgrading versions

The Supervisor will always be forwards compatible so you can just simply run newer versions. If there is data that must be normalized to a new schema such as the naming of engine resources, values in the sqlite database, etc then the new version will automatically take care of that either via migrations or at runtime when the value is queried.

However, these transformations of data are one way. You cannot run older versions of the Supervisor because the migrations are tracked in the sqlite database which will cause exceptions to be thrown once the Supervisor detects the source code is missing migration scripts that the database has. To resolve this just return to your previous Supervisor version or upgrade to the latest version if you don't remember.

License

Copyright 2020 Balena Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.