# Openbalena Getting Started Guide

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:

• The openBalena server, running Linux. These instructions were tested with an Ubuntu 18.04 x64 server.
• The local machine, running Linux, Windows or macOS where the balena CLI runs (as a client to the openBalena server). The local machine should also have a working installation of Docker so that application images can be built and deployed to your devices, although it is also possible to use balenaEngine on a balenaOS device instead of Docker.

### Preparing a server for openBalena​

Login to the server via SSH and run the following commands.

1. First, install or update essential software:

apt-get update && apt-get install -y build-essential git docker.io libssl-dev nodejs npm
2. Install docker-compose:

curl -L https://github.com/docker/compose/releases/download/1.27.4/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-composechmod +x /usr/local/bin/docker-compose

### Deploy an application​

The commands below should be run on a terminal on the local machine (where the balena CLI is installed). Ensure that the NODE_EXTRA_CA_CERTS environment variable is set, as discussed above.

Run 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 an application​

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 appsID APP NAME DEVICE TYPE  ONLINE DEVICES DEVICE COUNT1  myApp    raspberrypi3

#### Provision a new device​

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 devicesID UUID    DEVICE NAME  DEVICE TYPE  APPLICATION NAME STATUS IS ONLINE SUPERVISOR VERSION OS VERSION4  59d7700 winter-tree  raspberrypi3 myApp            Idle   true      11.14.0            balenaOS 2.58.3+rev1balena device 59d7700== WINTER TREEID:                 4DEVICE TYPE:        raspberrypi3STATUS:             onlineIS ONLINE:          trueIP ADDRESS:         192.168.43.247APPLICATION NAME:   myAppUUID:               59d7700755ec5de06783eda8034c9d3dSUPERVISOR VERSION: 11.14.0OS VERSION:         balenaOS 2.58.3+rev1

It's time to deploy code to the device.

#### Deploy a project​

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%%-alpineCMD [ "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!

## Next steps​

• Try out local mode, which allows you to build and sync code to your device locally for rapid development.
• Develop an application with multiple containers to provide a more modular approach to application management.
• Manage your device fleet with the use of configuration and environment variables.
• Explore our example projects to give you an idea of more things you can do with balena.
• If you find yourself stuck or confused, help is just a click away.
• Pin selected devices to selected code releases using sample scripts.
• To change the superuser password after setting the credentials, follow this forum post.