How to get started 'porting' existing Docker containers to balena?


I’m not a developer so my point of looking at balena has nothing to do with creating my own projects per se. However, I see balena as a cool way to run a number of docker containers in a way that’s much more convenient that just installing raspiOS and docker along with portainer on a rpi which is what I’ve been doing so far.

So my question is if there’s documentation pointed towards people like me, helping to ‘port’ existing docker containers to balena cloud? I guess it’s very much what has been done with e.g. pi-hole where whoever ported it to balena just extended the official pi-hole docker image. I don’t think it would be terribly hard just to mirror that but having real documentation would probably be easier.

What should I do here? I really like that you have a lot of docs - I just don’t really see it pointed very much to my use.



Hello Klaus,

Thank you for reaching out to us! A first step to porting the docker containers would be to ensure that you have the correct base image for your device and OS written at the top. Then, try to deploying to your device. Then look at the build logs for any errors. If you do see an errors, ensure that everything you are running in the docker container is compatible with the base image listed at the top of the dockerfile.

Thanks. So there’s no official documentation available?


Hi Klaus,

We do have getting started guides for every device supported by balena. The guides should help you from flashing the balenaOS image onto your device, to geting your services running on it: balenaOS - Docs

You should also be able to follow this guide to help you set up for balena: Define a container - Balena Documentation

If you’ll notice, you can still use your existing Dockerfiles to define the services that you want running on your device. However, if you want to modify your Dockerfiles to let balena automatically detect the device type that your service will be running on, you may want to use Dockerfile templates as shown in this section of the document: Define a container - Balena Documentation

You can also use docker-compose.yml files to define multiple services to run concurrently in your device. There are also labels that you can set to work with hardware attachments or to interact with the balena supervisor: docker-compose.yml fields - Balena Documentation

Note that the balena supervisor is the service that we run on your device to make sure that the services that you define are always running. The supervisor also connects to the balenaCloud to download any new releases that you want deployed onto your device.

Let us know if this is enough to help you get started.

All the best,