This guide will walk you through the steps of deploying an openBalena server, that together with the balena CLI, will enable you to create and manage a fleet of devices running on your own infrastructure, on premises or in the cloud. The openBalena servers must be reachable by the devices, which is easiest to achieve with cloud providers like AWS, Google Cloud, Digital Ocean and others.
This guide assumes a setup with two separate machines:
Login to the server via SSH and run the following commands.
First, install or update essential software:
$ apt-get update && apt-get install -y build-essential git docker.io libssl-dev nodejs npm
$ curl -L https://github.com/docker/compose/releases/download/1.27.4/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-compose $ chmod +x /usr/local/bin/docker-compose
Test your docker-compose installation with
$ docker-compose --version.
Create a new user, assign admin permissions and add to
$ adduser balena $ usermod -aG sudo balena $ usermod -aG docker balena
On the server still, login as the new user and change into the home directory:
$ su balena $ cd ~
Clone the openBalena repository and change into the new directory:
$ git clone https://github.com/balena-io/open-balena.git $ cd open-balena/
quickstart script as below. This will create a new
directory and generate appropriate SSL certificates and configuration for the
server. The provided email and password will be used to automatically create
the user account for interacting with the server and will be needed later on
for logging in via the balena CLI. Replace the domain name for the
$ ./scripts/quickstart -U <email@address> -P <password> -d mydomain.com
For more available options, see the script's help:
$ ./scripts/quickstart -h
At this point, the openBalena server can be started with:
$ systemctl start docker $ ./scripts/compose up -d
-d argument spawns the containers as background services.
Tail the logs of the containers with:
$ ./scripts/compose exec <service-name> journalctl -fn100
<service-name> with the name of any one of the services defined
The server can be stopped with:
$ ./scripts/compose stop
The following CNAME records must be configured to point to the openBalena server:
api.mydomain.com registry.mydomain.com vpn.mydomain.com s3.mydomain.com
Check with your internet domain name registrar for instructions on how to configure CNAME records.
To confirm that everything is running correctly, try a simple request from the local machine to the server:
$ curl -k https://api.mydomain.com/ping OK
Congratulations! The openBalena server is up and running. The next step is to setup the local machine to use the server, provision a device and deploy a small project.
The installation of the openBalena server produces a few self-signed certificates that must be installed on the local machine, so that it can securely communicate with the server.
The root certificate is found at
config/certs/root/ca.crt on the server. Copy
it to some folder on the local machine and keep a note the path -- it will be
used later during the CLI installation. Follow the steps below for the specific
platform of the local machine.
$ sudo cp ca.crt /usr/local/share/ca-certificates/ca.crt $ sudo update-ca-certificates $ sudo systemctl restart docker
$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt $ osascript -e 'quit app "Docker"' && open -a Docker
$ certutil -addstore -f "ROOT" ca.crt
The Docker daemon on the local machine must then be restarted for Docker to pick up the new certificate.
Follow the balena CLI installation instructions to install the balena CLI on the local machine.
By default, the CLI targets the balenaCloud servers at
needs to be configured to target the openBalena server instead. Add the following
line to the CLI's configuration file, replacing
"mydomain.com" with the domain
name of the openBalena server:
The CLI configuration file can be found at:
If the file does not already exist, just create it.
Wrapping up the CLI installation, set an environment variable that points to the root certificate copied previously on the local machine. This step is to ensure the CLI can securely interact with the openBalena server.
The commands below should be run on a terminal on the local machine (where the
balena CLI is installed). Ensure that the
variable is set, as discussed above.
balena login, select
Credentials and use the email and password
specified during quickstart to login to the openBalena server. At any time, the
balena whoami command may be used to check which server the CLI is logged in to.
Create a new application with
balena app create myApp. Select the application's
default device type with the interactive prompt. The examples in this guide assume
a Raspberry Pi 3.
An application contains devices that share the same architecture (such as ARM or Intel i386), and also contains code releases that are deployed to the devices. When a device is provisioned, it is added to an application, but can be migrated to another application at any time. There is no limit to the number of applications that can be created or to the number of devices that can be provisioned.
At any time, the server can be queried for all the applications it knows about with the following command:
$ balena apps ID APP NAME DEVICE TYPE ONLINE DEVICES DEVICE COUNT 1 myApp raspberrypi3
Once we have an application, it’s time to start provisioning devices. To do this, first download a balenaOS image from balena.io. Pick the development image that is appropriate for your device.
Unzip the downloaded image and use the balena CLI to configure it:
$ balena os configure ~/Downloads/balena-cloud-raspberrypi3-2.58.3+rev1-dev-v11.14.0.img --app myApp
Flash the configured image to an SD card using Etcher. Insert the SD card into the device and power it on. The device will register with the openBalena server and after about two minutes will be inspectable:
$ balena devices ID UUID DEVICE NAME DEVICE TYPE APPLICATION NAME STATUS IS ONLINE SUPERVISOR VERSION OS VERSION 4 59d7700 winter-tree raspberrypi3 myApp Idle true 11.14.0 balenaOS 2.58.3+rev1 $ balena device 59d7700 == WINTER TREE ID: 4 DEVICE TYPE: raspberrypi3 STATUS: online IS ONLINE: true IP ADDRESS: 192.168.43.247 APPLICATION NAME: myApp UUID: 59d7700755ec5de06783eda8034c9d3d SUPERVISOR VERSION: 11.14.0 OS VERSION: balenaOS 2.58.3+rev1
It's time to deploy code to the device.
Application release images are built on the local machine using the balena CLI. Ensure the root certificate has been correctly installed on the local machine, as discussed above.
Let's create a trivial project that logs "Idling...". On an empty directory,
create a new file named
Dockerfile.template with the following contents:
FROM balenalib/%%BALENA_MACHINE_NAME%%-alpine CMD [ "balena-idle" ]
Then build and deploy the project with:
$ balena deploy myApp --logs
The project will have been successfully built when a friendly unicorn appears in the terminal:
[Info] Compose file detected ... [Info] Creating release... [Info] Pushing images to registry... [Info] Saving release... [Success] Deploy succeeded! [Success] Release: f62a74c220b92949ec78761c74366046 \ \ \\ \\ >\/7 _.-(6' \ (=___._/` \ ) \ | / / | / > / j < _\ _.-' : ``. \ r=._\ `. <`\\_ \ .`-. \ r-7 `-. ._ ' . `\ \`, `-.`7 7) ) \/ \| \' / `-._ || .' \\ ( >\ > ,.-' >.' <.'_.'' <'
This command packages up the local directory, creates a new Docker image from it and pushes it to the openBalena server. In turn, the server will deploy it to all provisioned devices and within a couple of minutes, they will all run the new release. Logs can be viewed with:
$ balena logs 59d7700 --tail [Logs] [10/28/2020, 11:40:16 AM] Supervisor starting [Logs] [10/28/2020, 11:40:50 AM] Creating network 'default' [Logs] [10/28/2020, 11:42:38 AM] Creating volume 'resin-data' [Logs] [10/28/2020, 11:42:40 AM] Downloading image … … [Logs] [10/28/2020, 11:44:00 AM] [main] Idling...
Enjoy Balenafying All the Things!