Balena / Docker image from bootable sd card?


I am a Newbie, very much appreciate the help I get!!!

The company I work for is going to start using Balena for the products it delivers, the product is a large piece of equipment with fairly complex electronics and corresponding software that uses Raspberry Pi as a “master controller”. The RPi is running Raspbian with a some of our software, and couple custom/proprietary third party drivers installed along with some udev changes and other “stuff”.

My Boss thinks we should be able to create an balena base image from this customized sd card / image to be managed by balena.

From what I have read thus far, it seems to me, we have to basically build the images as docker containers before we can have them managed by the balena eco-system.

Can somebody help clarify my confusion.

Thank Y’all very much in advance!

  • Rusty Eddy

Hello @rustyeddy

Glad you are going to become balena users and welcome to our forums!

Devices managed with balena platform run balenaOS as their operating system. The OS also includes a docker engine suited for the IoT devices (balenaEngine) which is used to deploy and run user applications on the device.

The software you currently have running on Raspbian will need to be packaged in a form of Docker images, so you can ship it to the devices with our platform. To have a quick start, I would recommend quick start guides on our docs site
or experimenting with one of our DIY projects on the blog


Packaging device drivers may be challenging though depending on their nature. For instance, if you need kernel modules, you will have to compile them against our OS header files during Docker image build and then load them in your container entry point.
An example of how this can be done is given in the following github repo:

(you will find scripts that fetch kernel headers for a specific balenaOS version, compile them, and load)

I would also suggest checking the following docs related to the topic of interacting with hardware from Docker containers and working with UDEV rules.

Hope this helps.

It does help, Thank you very much for the prompt and detailed response. I do say there are some interesting projects.

I guess, we were hoping for a magic disk to docker image translator, but alas, I realize that was just wishful thinking.

Again, thank you very much for the prompt and detailed response!

  • rusty

Hi @rustyeddy,

We have a team at balena that specializes in these kinds of things, and I am checking in with them for more information about your usecase. In the meantime, I recommend reading this blogpost ( which details a client’s brownfield migration to balenaCloud.

Thanks again for reaching out!


Awesome, thank you for contacting your team, we are very interested to hear what they have to say.

Also, I watched the video and will dig into the article, but I think this is very similar to our situation regarding the “Brownfield deployment”, except that we are at a much smaller scale.

Looking forward to what your team has to say!


  • rusty

Hi @rustyeddy .
I am in charge of what we call brownfield migration in balena. This is the process of taking a device in the field running on a non balena OS and turning it into a device running balena OS. The process typically involves transferring a migration environment to the device (typically about 140MB including the OS image) and running the migrator on the device with root privileges.
The migrator has options that allow creating a backup of required data and transferring this data to the applications containers that will be running your application in balena.
Brownfield migration does not help you migrate your application into a container and make it balena-compatible though. It just allows you to deploy balenaOS and your balena application to devices in the field running other OS’ses than balena.

Reading through this thread I believe that migrating your application might be a two step process. You mentioned custom drivers and other ‘stuff’ that you will want to run on the device.
The first step would be to containerize your application and see how you get your software to run in containers on balena. If this is not straight forward, balena support might be able to point you in the right direction.
First step would be to identify potentially problematic software like special device drivers and figure out how you can run them inside balena.
There is a repository demonstrating how to add custom kernel modules to balena here:

Once you have a balena OS image and a working application, we can set up an environment to migrate devices that are already deployed using a different OS.

Hello @samothx, thank you for the info.

Our biggest challenge, I think is properly creating the containers around our apps is the biggest challenge. The “good news” is we are just now shipping our first actual product, so we do not have much of an existing deployment to worry about.

Our challenge is properly creating the containers ASAP such that we ship as few pre-balena units as possible…

I am sure I will be back with more, specific questions creating the containers.

One again, Your feedback is very helpful!

Thank You.

  • rusty