• Stars
    star
    147
  • Rank 251,347 (Top 5 %)
  • Language
    TypeScript
  • License
    Other
  • Created about 9 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Balena Supervisor: balena's agent on devices.

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)

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 [email protected]: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. If you get stuck at some point please reference the troubleshooting section before creating an issue.

Developing the supervisor

By far the most convenient way to develop the supervisor 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

> [email protected] 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

> [email protected] 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 \
[email protected]
# 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 v12.16.2, 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

# In another terminal, access the sut container
docker-compose exec -i sut sh

# Or alternatively, access the sut container using docker exec
docker exec -ti $(docker ps -q --filter="name=_sut") sh

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.

Troubleshooting

Make sure you are running at least:

node -v       # >= 12.16.2
npm -v        # >= 6.14.4
git --version # >= 2.13.0

Also, ensure you're installing dependencies with npm ci as this will perform a clean install and guarantee the module versions specified are downloaded rather then installed which might attempt to upgrade!

If you have upgraded system packages and find that your tests are failing to initialize with docker network errors, a reboot may resolve this. See this issue for details.

DBus

When developing on macOS you may need to install DBus on the development host.

  1. brew install dbus
  2. npm ci

On Debian-based systems, sudo apt install libdbus-1-dev would be the equivalent.

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.

More Repositories

1

wifi-connect

Easy WiFi setup for Linux devices from your mobile phone or laptop
Rust
1,264
star
2

meta-balena

A collection of Yocto layers used to build balenaOS images
BitBake
967
star
3

balena-engine

Moby-based Container Engine for Embedded, IoT, and Edge uses
Go
686
star
4

balena-raspberrypi

Balena support for RaspberryPI boards
BitBake
190
star
5

balena-os

The central place for all things BalenaOS related.
113
star
6

jetson-flash

This tool allows users to flash BalenaOS on Jetson supported devices
JavaScript
63
star
7

balenaos-in-container

Run balenaOS as a docker container
Shell
49
star
8

balena-jetson

BitBake
44
star
9

kernel-module-build

Example project for building an OOT kernel module in balena
Shell
35
star
10

balenahup

BALENA Host os UPdater
Shell
35
star
11

balena-intel

Balena support for Intel boards
BitBake
33
star
12

librsync-go

Pure Go implementation of librsync/rdiff
Go
31
star
13

configizer

Safe(r) balenaOS config.json updates remotely
Shell
26
star
14

leviathan

A distributed hardware testing framework
JavaScript
23
star
15

balena-allwinner

BitBake
20
star
16

balena-beaglebone

Balena support for Beaglebone boards
BitBake
20
star
17

balena-yocto-scripts

Helper scripts for balena yocto builds
Shell
20
star
18

balena-os-device-support

A list of current, proposed and planned future balena.io supported boards
19
star
19

balena-odroid

Balena support for ODROID boards
BitBake
15
star
20

healthdog-rs

Helper program that connects external periodic heathchecks with systemd's watchdog support
Rust
15
star
21

resin-device-toolbox

[DEPRECATED] The official Resin Device Toolbox CLI for resinOS
CoffeeScript
14
star
22

balena-radxa

BitBake
13
star
23

module-headers

Tool for generating kernel module headers from kernel source. Heavily based on arch's x86-64 PKGBUILD.
Shell
13
star
24

balena-variscite-mx8

BitBake
11
star
25

meta-artik

BSP Yocto layer for Samsung Artik board
BitBake
11
star
26

takeover

Migrate arbitrary devices to balena
Rust
11
star
27

balena-asus-tinker-board

CoffeeScript
10
star
28

balena-generic

Balena support for generic devices
BitBake
9
star
29

balena-image-flasher-unwrap

Tool for unwrapping balena-image from a balena-image-flasher
Shell
8
star
30

balena-fsl-arm

Balena support for Freescale boards
BitBake
8
star
31

serial-it

Shell
7
star
32

balena-qemu

Balena support for QEMU boards
CoffeeScript
7
star
33

os-config

Rust
6
star
34

balena-jetson-orin

Balena integration repository for Jetson Orin devices
Shell
6
star
35

linux-artik7

Linux kernel for Artik 710
C
6
star
36

balena-artik

Balena support for Artik boards
CoffeeScript
6
star
37

balena-up-board

Balena support for UP board
BitBake
6
star
38

leviathan-worker

The worker layer for Leviathan including worker plugins QemuKit & AutoKit
TypeScript
6
star
39

balena-edison

Balena support for Edison boards
Roff
6
star
40

balena-seeed-x86

BitBake
5
star
41

balena-iot-gate-imx8

Shell
5
star
42

balenaosversions

List of released OS versions for different devices on Balena Cloud
JavaScript
5
star
43

poky

Python
4
star
44

bindmount

Rust
4
star
45

balena-coral

BitBake
4
star
46

balena-nanopc-t4

BitBake
4
star
47

balenafin-raspbian

Raspbian support for balenaFin
Shell
4
star
48

uboot-artik7

uBoot for Artik 710
C
4
star
49

balena-isg

Support for Rocktech ISG boards
BitBake
4
star
50

balena-board-template

This is a template to be used for new board support repositories.
4
star
51

mobynit

Package to mount hostapp filessytems
Go
4
star
52

balena-iot-gate-imx8plus

BitBake
3
star
53

balena-variscite

Balena support for Variscite boards
BitBake
3
star
54

balena-owa5x

BitBake
3
star
55

migrate

Migrate brownfield devices to Balena
Rust
3
star
56

balena-benchmarks

Benchmarks for balaena
Shell
3
star
57

meta-edison-bsp

C
3
star
58

balena-artik710

Balena support for Artik 710 boards
CoffeeScript
3
star
59

balena-am571x-evm

Balena support for am57xx-evm boards
CoffeeScript
3
star
60

balena-intel-quark

Balena support for intel-quark boards
JavaScript
3
star
61

meta-artik710

BSP Yocto layer for Samsung Artik 710 board and Co
BitBake
3
star
62

build-artik

Scripts and prebuilts for artik boards
Shell
3
star
63

fatrw

CLI utility and a Rust library that implements safe file read and write operations for FAT file systems
Rust
3
star
64

balena-compulab

BitBake
3
star
65

balena-toradex

Balena support for Toradex boards
CoffeeScript
3
star
66

meta-resin-extra

meta-resin-extra is a Yocto layer used to build extra/optional package on top of meta-resin
BitBake
3
star
67

cloud-config

balenaCloud application used to configure balenaOS from supported metadata services
Shell
3
star
68

balena-chip

Balena support for C.H.I.P. boards
CoffeeScript
3
star
69

balena-ts

Balena support for TS boards
CoffeeScript
3
star
70

balena-parallella

Balena support for Parallella boards
CoffeeScript
3
star
71

balena-iot2000

Balena support for the Siemens IOT2000 family
CoffeeScript
3
star
72

brcm_patchram_plus

Broadcom utility to upload firmware on bluetooth chips
C
3
star
73

resin-provisioner

Supervisor component for provisioning a device against resin servers.
Go
3
star
74

balena-sign

Service used to sign data over the network and retrieve the respective public keys
Python
3
star
75

balena-tci

Shell
2
star
76

resinos-tests-legacy

Shell
2
star
77

test-helpers

TypeScript
2
star
78

meta-tegra

BitBake
2
star
79

meta-tinker-board

BSP yocto layer for Asus Tinker Board
BitBake
2
star
80

renovate-config

Shared renovate configuration and GitHub Action
2
star
81

iot-gate-imx8plus-flashtools

Container scripts for flashing Compulab IOT-GATE-iMX8PLUS with BalenaOS
Shell
2
star
82

balena-jetson-wnb

BitBake
2
star
83

balena-rockpro64

BitBake
2
star
84

gazette

A lightweight log collection service for sending system logs to the balena API
Shell
2
star
85

balena-revpi

BalenaOS integration layer for the Revolution Pi boards
C++
2
star
86

balena-zc702

Balena support for ZYNQ ZC702 boards
CoffeeScript
2
star
87

balena-topic

BitBake
2
star
88

log-streamer

Test sending logs to the API log-stream
TypeScript
2
star
89

balenaos-extra-tools

Shell
2
star
90

colibri-ddr-patch

WIP: Patch DDR size in Colibri boards
C
2
star
91

github-workflows

A collection of reusable github workflows
2
star
92

balena-via-arm

Balena support for VAB820 boards
CoffeeScript
2
star
93

resin-edge

Resin support for edge devices build environment
Shell
2
star
94

balena-connectcore

BalenaOS for the Digi ConnectCore SBCs and System-On-Modules
BitBake
2
star
95

balena-nanopi-r2

BitBake
2
star
96

qemukit

Qemukit helps in writing automated tests on Qemu environments
TypeScript
2
star
97

amber-etcher-kernel

Shell
2
star
98

meta-radxa-rockpi

1
star
99

balena-ts-7970

1
star
100

balenaos-contracts

A collection of meta-data for BalenaOS extensions
1
star