Develop with blocks
A block is a container image that can be added to a multicontainer fleet in order to provide specific functionality. Blocks are intended to reduce the friction of app development by making it easier to re-use functionality, much like software packages.
Similar to how software developers don't want to keep rewriting common functions, IOT developers don't want to keep creating containers for common tasks, such as handling Bluetooth connections or interacting with attached displays. Blocks provide solutions to common IoT application requirements, which developers can re-use to enable their fleet.
For example, getting a browser to run well in a container is a tedious task. Hence, why not use the browser block to get things up and running faster..
Getting Started with blocks
Since blocks are container images, they can be added to a multicontainer fleet. To use a block in your fleet, add the block's image as a new service in the
services section of your app's
docker-compose.yml file. This is similar to how we would build multicontainer fleets.
Here's an example of using the browser block in a sample multicontainer fleet already running 2 services.
version: '2' services: # Browser block service added to the multicontainer fleet browser: image: balenablocks/browser privileged: true network_mode: host # Existing services in the multicontainer fleet balena-node-hello-world: build: ./balena-node-hello-world restart: always depends_on: - browser ports: - "80" importantBananaDb: image: importantBanana/db:latest ports: - "8080" environment: DB_ROOT_PASSWORD: 'potassium' RUN_MODE: 'super-secure'
Each block will have their own set of docker-compose fields which are required to configure the container they run within. Do take care of syntax and conflicts in the docker-compose.yml file when composing and deploying your multicontainer configuration.
- Blog on Introduction to blocks.
- Check out our guide on how to compose multicontainer fleets for more details.
- Video tutorial on IoT Happy Hour about using balenaBlocks and building an environmental sensor app using sensor, connector, and dashboard block.
Creating your own block
Since blocks are container images, the process to create them is very similar to creating any other container. To learn more about what makes a good candidate for a block, refer to this blog post.
In order to create your own block, the code needs to be in a GitHub repository. It has to include a balena.yml file in the root directory of the project. Here's a balena.yml file of the browser block for reference:
name: browser description: >- a hardware accelerated web browser to present internal and external URLs on a connected display version: 2.3.2 type: sw.block assets: repository: type: blob.asset data: url: 'https://github.com/balenablocks/browser' logo: type: blob.asset data: url: 'https://raw.githubusercontent.com/balenablocks/browser/master/logo.png' data: defaultDeviceType: raspberrypi3 supportedDeviceTypes: - raspberrypi4-64 - fincm3 - raspberrypi3 - raspberrypi3-64 - raspberrypi400-64 - intel-nuc - genericx86-64-ext
Next, navigate to the
Blocks tab in the sidebar and click the
Create block button in the balenaCloud dashboard.
Fill the details for your block in the modal, and click
Create new block button to create your block.
Next, we have to push a new release from your project to your newly created block on balenaCloud. If you are new to this, then follow the Getting Started guide. After the release has been created, your block is ready. You can manage, modify and iterate further on your block from the balenaCloud dashboard.
Release management for blocks
By default, the block is set to
track latest, which means that new releases are immediately tagged as the default release for the block. Expanding this Default release dropdown menu displays all successful releases for the block, and you can select a specific release to pin the block to. When a particular release is selected, that release will be tagged as the default release of your block. After pinning to a specific release, releases will not be deployed until the Default release is updated to a newer release or it's set back to
Making your block public
When a block is created on balenaCloud it will not automatically be publicly visible on balenaHub. When a block is made public it is listed in the Blocks section of balenaHub, but is not joinable like fleets or forkable like projects. Instead the card for the block allows users to find the source code for the block, and learn how to deploy and use it in their own fleet.
When blocks are private, you can iterate, test and build more functionality before making it available to the world. When you are ready to release, head to the
Settings tab in the sidebar and add your block's GitHub repository to the
Repository URL section. Next, toggle the
Block visibility button to
on for your block to be visible on balenaHub. You’re free to toggle the visibility on and off as necessary at any time.
This would lead to your block being available on balenaHub for folks to use and build upon as soon as your submission has been marked as public. BalenaHub is the ever-growing library of blocks, projects and fleets contributed by the community.