How can I build a custom image from balena-raspberrypi?

I want to build a custom image with a service installed and started in default.
I am checking this link to build my custom image, but not sure how to make it start my own service(docker container, actually) at the booting time:

Any idea?


Hello @scarlyon, could you describe a bit what you are trying to do so we can better help you?

Depending on your goals, you don’t need to make a custom image but select one of the ones we already have and install/configure packages inside it.

All the best


Thanks for your quick reply!

We are downloading image files from and flashing to a micro sd card, right?
After flashing it, I am seeing a docker container(acutally balena-supervisor) already running.

So I want to make my container running once the img file is flashed.

How can I configure the .img file? Maybe /boot/config.json?
Otherwise, should I build my custom own image?



I wonder if you really need custom image. Your goal is to have a device that is connected to balenaCloud and you’d like to preload your application / services images to the SD card, so, the device is not forced to download it once booted. Am I right? If yes, isn’t balena preload what you’re looking for?


Yeah, so let’s say that I need this sample service running at the first booting time of an image -

How can I configure the image file to preload this service?



here’re steps to follow …

  • create an application (balenaCloud)
  • git push simple-server-python to balena origin
  • get the application ID (it’s in the dashboard URL)
  • visit Releases and copy the release UUID
  • download OS image (even via add device button)
  • unzip the OS image

… and run …

balena preload $UNZIPPED_IMAGE_PATH --app $APP_ID --commit $APP_RELEASE


balena preload ./balena-cloud-python-raspberrypi3-2.36.0+rev2-dev-v9.15.0.img --app 1470061 --commit f9d139ca31b8594f90d7b9098b1353b14c

You’ll be asked:

This application is set to automatically update all devices to the latest available version.
This might be unexpected behaviour: with this enabled, the preloaded device will still
download and install the latest release once it is online.

Do you want to disable automatic updates for this application?

Warning: To re-enable this requires direct api calls,

Alternatively you can pass the --pin-device-to-release flag to pin only this device to the selected release.

Answer yes to allow to pin the device to this release or no to allow future updates.

Insert the SD card into RPi and boot it.

Docker must be running on your computer. If you’re on macOS, use Docker Community Edition 18.06.1-ce-mac73 2018-08-29 and don’t update it. See this issue for more info.

Does it help?

And once the device is booted, you can check in the supervisor logs that the images weren’t downloaded: journalctl -u resin-supervisor.

Wow, thanks for your detailed explanation!

Much appreciated! :slight_smile:


By the way, I want to use open-balena server instead of balena cloud.
Any idea? :joy:


you can preload it even for openBalena. Here’s thread about it where you can also learn which balena CLI version you need and how to use new --add-certificate option, etc.

1 Like