Get started with Balena Fin (CM3) and Node.js
In this guide, we will build a simple Node.js web server project on a Balena Fin (CM3). At its most basic, the process for deploying code to a Balena Fin (CM3) consists of two major steps:
- Setting up your Balena Fin (CM3) with balenaOS, the host OS that manages communication with balenaCloud and runs the core device operations.
- Pushing your Node.js project to the balena image builder, which pulls in all necessary dependencies and creates the container image for your application.
Once you complete these steps, your Balena Fin (CM3) will download the container image, start your application, and begin sending logs to your balena dashboard!
What you will need
- A Balena Fin. See our supported devices list for other boards.
- A 5.5/2.1mm Barrel Jack Power supply rated at 6 - 24 Vdc. It is also possible to power the fin via the phoenix connector next to the barrel jack, be sure to never apply power to both connectors simultaneously!
- A micro USB cable.
- [Optional] An ethernet cable.
- A balena account.
If you don't already have a balena account, make sure to sign up before continuing.
Create an application
An application is a group of devices that share the same architecture and run the same code. When you provision a device, it is added to a specific application, but can be migrated to another application at any time.
To create your first application, log into your balenaCloud dashboard and click the Create application button.
Select the Balena Fin (CM3) device type, choose an application type, enter a name, and click Create new application:
Note: To create an application with multiple containers, you'll want to use the Starter or Microservices application type. The Starter applications are full-featured and free for all users, with a limit of up to 10 total devices across all Starter applications.
After the application has been created, you will be redirected to the dashboard for the newly created application, where you can add your first Balena Fin (CM3).
Add your first device
To connect with balenaCloud, your Balena Fin (CM3) needs a balenaOS image configured for your device type, application, and network. Start by clicking Add device in your application dashboard:
For most applications, you will have the option to select a device type. By default, the device type you chose when you first created the application will be selected. Applications can, however, support any devices that share the same architecture, so you can choose another device type if needed.
After selecting a device type, select an OS type of balenaOS, and you will see a list of available balenaOS versions. In general, you should use the most recent version available. You can also select whether to use a Development or Production edition with the respective toggle:
Note: When you're getting started, a Development image is the most useful, as it permits many testing and troubleshooting features. For production use, be sure to switch to a Production image. More details on the differences between Development and Production images are detailed here.
A toggle is also used to select whether your network connection will be through Ethernet Only or with the option for Wifi + Ethernet. Selecting Wifi + Ethernet allows you to enter a Wifi SSID and Wifi Passphrase:
Clicking Advanced presents the option to select the rate at which your device checks for updates:
Once you have finished your image configuration, click the Download balenaOS button. When the download completes, you should have a zipped image file with a name like
First-App is the name you gave your application on the dashboard.
Alternatively, by clicking on the toggle section of the download button, you also have the option to download just a configuration file (
config.json) rather than an entire image.
The next step is to flash the downloaded image onto your Balena Fin (CM3)'s internal eMMC. The easiest way to flash the image onto the device is using balena’s Etcher. Support for the CM3L is available on Etcher starting from version 1.2.1 for OSX and Windows (Windows still needs the Raspberry Pi Foundation usbboot drivers installed).
The Raspberry Pi Foundation provides a tool that allows the Compute Module to expose the eMMC as a mass storage device that can be flashed like any other media. If you want to use the tool provided by the Raspberry Pi Foundation instead, please follow their instructions here.
Once you have everything set up, run Etcher on your computer, connect your balena Fin via CM3L Debug (see USB_DBG on Image 1) and power it (see BARREL_JACK on Image 1).
After a couple of seconds, the balena Fin eMMC should be detected on your computer by Etcher, which will initialize and list the board as a Compute Module based device (naming might change in the future). Select the downloaded image and press the “Flash!” button.
After flash is complete, power off your balena Fin and unplug the DEBUG micro-USB cable. Powering the balena Fin on will now result in the device booting from the freshly-written eMMC.
Note: You can flash several Balena Fin (CM3)s with the same OS image file and all the devices will boot and provision into your application's fleet. You can also disable the auto-ejecting or validation steps from the Etcher settings panel.
Now that we have a device or two connected to a balena application, let's deploy some code.
The recommended way to deploy code is to use the balena CLI. Follow the installation
instructions. After it is installed, login to your balena account
balena login command on the terminal:
$ balena login _ _ | |__ __ _ | | ____ _ __ __ _ | '_ \ / _` || | / __ \| '_ \ / _` | | |_) | (_) || || ___/| | | || (_) | |_.__/ \__,_||_| \____/|_| |_| \__,_| Logging in to balena-cloud.com ? How would you like to login? (Use arrow keys) ❯ Web authorization (recommended) Credentials Authentication token I don't have a balena account!
You will be asked to choose an authentication method. Choosing Web authorization will bring up a web browser window that allows you to login to your balenaCloud account. When asked to authorize the CLI, click the Authorize button and head back to the terminal.
Note: Other authentication methods include using your username and password credentials or obtaining an authentication token from the dashboard. Authentication tokens come in two types, API tokens, and JSON Web Token (JWT) session tokens. While API tokens do not expire, JWT session tokens do after 7 days.
After logging in, test out the balena CLI by running the
balena apps command, which should return information about the application you created in the previous step. Take a note of the
APP NAME as you'll need this in the next step to push the code to all devices in that application.
$ balena apps ID APP NAME DEVICE TYPE ONLINE DEVICES DEVICE COUNT 98264 First-App Balena Fin (CM3) 0 0
Note: See all the commands available with balena CLI by running
A nice first project to get started is balena-node-hello-world, an Express.js web server that serves a static page on port
Note: You may also use git to deploy code to a device. If you wish to deploy via git, see the instructions here.
Now to deploy this code to all device(s) in the application, use the
balena push First-App command replacing
First-App with the name of your application. Ensure you are in the root of the project directory before issuing this command or specify the
--source option to provide an alternate location of the project directory.
$ balena push First-App
This command will package up and push the code from the local directory to the balena builders, where it will be compiled, built and deployed to every device in the application fleet.
You'll know your code has been successfully compiled and built when our friendly unicorn mascot appears in your terminal:
[main] Successfully built d5f1de77fad3 [Info] Uploading images [Success] Successfully uploaded images [Success] Release successfully created! [Info] Release: f4e3925bf7d32226365225e1b7201b90 (id: 89693) [Info] ┌─────────┬────────────┬────────────┐ [Info] │ Service │ Image Size │ Build Time │ [Info] ├─────────┼────────────┼────────────┤ [Info] │ main │ 205.13 MB │ 1 second │ [Info] └─────────┴────────────┴────────────┘ [Info] Build finished in 7 seconds \ \ \\ \\ >\/7 _.-(6' \ (=___._/` \ ) \ | / / | / > / j < _\ _.-' : ``. \ r=._\ `. <`\\_ \ .`-. \ r-7 `-. ._ ' . `\ \`, `-.`7 7) ) \/ \| \' / `-._ || .' \\ ( >\ > ,.-' >.' <.'_.'' <'
Your application will then be downloaded and executed by all the devices you have connected in your application fleet. The first push is slower to deploy, but all subsequent pushes are much faster due to Docker layer sharing. You can see the progress of the device code updates on the device dashboard:
You should now have a node.js web server running on your device and see some logs on your dashboard.
To give your device a public URL, access the device page, and choose the Public Device URL toggle. You may also activate this for many devices in your fleet at the same time via the Actions menu in the Applications dashboard.
Follow the URL to view a page with additional balena learning resources and next steps. Alternatively, you can point your browser to your device's IP address.
- Head to balenaHub, for more ready-to-deploy applications, or have a go at building and sharing your own cool projects using balenaBlocks.
- 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, environment, and service variables.
- Visit our blog to find step-by-step tutorials for some classic balena projects.
- If you find yourself stuck or confused, help is just a click away.
Enjoy Balenafying All the Things!