First Step - setup OpenBalena server

This guide was taken from https://www.balena.io/open/docs/getting-started​

IMPORTANT!

If you already had setup openBalena server you can skip this part to the Github Actions server preparation​

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

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-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 docker group:

$ adduser balena
$ usermod -aG sudo balena
$ usermod -aG docker balena

Install openBalena on the server

1. On the server still, login as the new user and change into the home directory:

   $ su balena
   $ cd ~

2. Clone the openBalena repository and change into the new directory:

   $ git clone https://github.com/balena-io/open-balena.git
   $ cd open-balena/

3. Run the quickstart script as below. This will create a new config 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 -d argument appropriately.

   $ ./scripts/quickstart -U <[email protected]> -P <password> -d mydomain.com

   For more available options, see the script's help:

   $ ./scripts/quickstart -h

4. At this point, the openBalena server can be started with:

   $ systemctl start docker
   $ ./scripts/compose up -d

   The -d argument spawns the containers as background services.

5. Tail the logs of the containers with:

   $ ./scripts/compose exec <service-name> journalctl -fn100

   Replace <service-name> with the name of any one of the services defined in compose/services.yml; eg. api or registry.

6. The server can be stopped with:

   $ ./scripts/compose stop

When updating openBalena to a new version, the steps are:

$ ./scripts/compose down
$ git pull
$ ./scripts/compose build
$ ./scripts/compose up -d

Domain Configuration

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
tunnel.mydomain.com

Check with your internet domain name registrar for instructions on how to configure CNAME records.

For example IP of your server is 100.100.100.100and your domain is mydomain.con

Main A record must to point exactly to 100.100.100.100

After setup A record - you will need to set up the CNAME records mentioned above. They must point to your domain mydomain.con

Test the openBalena server

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.

OpenBalena configuration part is ended.

Prepare to install Github Actions Runner

Install self-signed certificates on openBalena server

The installation of the openBalena server produces a few self-signed certificates that must be installed on the local machine, or your Github Worker so that it can securely communicate with the server.

The root certificate is found at config/certs/root/ca.crt on the server.

SSH into the machine with openBalena server, and log in as balena user.

Linux:

$ su balena
$ cd ~
$ sudo cp open-balena/config/certs/root/ca.crt /usr/local/share/ca-certificates/ca.crt
$ sudo update-ca-certificates
$ sudo systemctl restart docker

The Docker daemon on the local machine must then be restarted for Docker to pick up the new certificate.

After daemon restarted - you must restart your OpenBalena server with commands:

$ ./scripts/compose down
$ ./scripts/compose up -d

Create a user for actions and login

Create a new user, assign admin permissions and add to docker group:

$ adduser github
$ usermod -aG sudo github
$ usermod -aG docker github

1. On the server still, login as the new github user and change into the home directory:

   $ su github
   $ cd ~

​Adding a self-hosted runner to a repository​

You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings.

1. In the left sidebar, click Actions.​

2. Under "Self-hosted runners," click Add runner.

3. Select the operating system and architecture of your self-hosted runner machine.

4. You will see instructions showing you how to download the runner application and install it on your self-hosted runner machine.

   Open a shell on your openBalena server, login to already created github user and run each shell command in the order shown.

   The instructions walk you through completing these tasks:

   • Downloading and extracting the self-hosted runner application.

   • Running the config script to configure the self-hosted runner application and register it with GitHub Actions. The config script requires the destination URL and an automatically-generated time-limited token to authenticate the request.

   • Running the self-hosted runner application to connect the machine to GitHub Actions.

Checking that your self-hosted runner was successfully added

After completing the steps to add a self-hosted runner, the runner and its status are now listed under "Self-hosted runners".

The self-hosted runner application must be active for the runner to accept jobs. When the runner application is connected to GitHub and ready to receive jobs, you will see the following message on machine's terminal.

√ Connected to GitHub
​
2019-10-24 05:45:56Z: Listening for Jobs

​Adding a self-hosted runner to an organization​

You can add self-hosted runners at the organization level, where they can be used to process jobs for multiple repositories in an organization. To add a self-hosted runner to an organization, you must be an organization owner.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Settings.​

3. In the left sidebar, click Actions.​

4. Under "Self-hosted runners," click Add new, then click New runner.

5. Select the operating system and architecture of your self-hosted runner machine.​

6. You will see instructions showing you the same path for installing a self-hosted runner.

You must add a runner to GitHub before you can configure the self-hosted runner application as a service. For more information, see "Adding self-hosted runners."

For Linux systems that use systemd, you can use the svc.sh script distributed with the self-hosted runner application to install and manage using the application as a service.

On the runner machine, open a shell in the directory where you installed the self-hosted runner application. Use the commands below to install and manage the self-hosted runner service.

​Installing runner as a service

1. Stop the self-hosted runner application if it is currently running.

2. Install the service with the following command:

   sudo ./svc.sh install

​Starting the service​

Start the service with the following command:

sudo ./svc.sh start

​Checking the status of the service​

Check the status of the service with the following command:

sudo ./svc.sh status

For more information on viewing the status of your self-hosted runner, see "Monitoring and troubleshooting self-hosted runners."

Add balena-cli action for your openBalena project repo

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Actions.

3. Press the New workflow button to start create your own workflow

4. Select set up a workflow yourself option

5. Open openBalena balenaCLI Github Actions action

6. Using the example replace the default workflow

Replace this:

With:

name: OpenBalena Deploy
​
on:
  push:
    # Only run workflow for pushes to specific branches
    branches:
      - master
​
jobs:
  balena-deploy:
    runs-on: self-hosted #IMPORTANT line which set that you will use self-hosted runner
    steps:
      - name: Checkout
        uses: actions/[email protected]
      - name: Balena Deploy
        uses: Solar-Control/[email protected]
        if: success()
        with:
          balena_api_token: ${{secrets.BALENA_API_TOKEN}} #Create balenaToken using CLI at your local machine
          balena_command: "deploy my-awesome-app --logs" #Here you can use your variant of command for balena
          open_balena_address: ${{secrets.OPEN_BALENA_ADDRESS}} #This must to point for your openBalena server address like mydomain.com NOT api.mydomain.com
          root_cert: ${{secrets.OPEN_BALENA_ROOT_CERT}} # IMPORTANT - ca.crt must to be inlined with \n symbols

After saving the workflow file - the first build will fail cause of the absence of variables.

Add secrets to your repository

To make it works you need to add secrets as variables to your GitHub repo with this workflow.

Secrets is a secure way to save variables in repos so here we go:

• Open Settings tab at your repository

• Choose Secrets tab

• Start adding your secrets to repo with New repository secret button

• Add all secrets mentioned in the workflow on this page

BALENA_API_TOKEN - Create balenaToken using CLI at your local machine

OPEN_BALENA_ADDRESS - This must to point for your openBalena server address like mydomain.com NOT api.mydomain.com

OPEN_BALENA_ROOT_CERT

*IMPORTANT - ca.crt must to be inlined with \n symbols

Use awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' ca.crt to inline your crt file - copy output and paste it to value input.

• After adding you must see these 3 secrets in secrets list

Finish!

Well done - you are ended with creating your own balena push analog with using open-source alternatives!

Just git push to your repo, and your code will deploy to the openBalena server!

There are a lot of options to use different workers and machines!

Also, there is a possibility to modify your workflow file to create artifacts for Github docker-registry or create custom os images and publish artifacts on your Github Repo.

Thank you for your attention!