Improve this doc

Custom Base Images for your Fleet

Raspbian and Debian are great, but sometimes you just want to let your hair loose and get crazy with Arch Linux or some other distro. With balena this is actually pretty easy and what follows are a few simple steps to get your own custom base image.

Note: This guide assumes some knowledge of Docker and expects that you have Docker or somekind or boot2docker installed on your host machine. It also expects you to have an account over at the Docker Hub.

Step 1:

First things, first. Find image you like on Docker Hub or build your own from here. Remember this image needs to be architecture specific, i.e. an Ubuntu base image is not going to work on your raspberry pi B+.

For this step, we selected digitallyseamless/archlinux-armv6h, which is an Arch Linux distribution targeting armv6, the architecture of the raspberry pi A and B.

Note: The newer Raspberry Pi 2 has a different architecture based on armv7 and will in fact work with Ubuntu.

Step 2:

Next clone this repo and edit the Dockerfile, so that it bases from the Docker Hubimage you selected in step 1. This is what it should look like for the Arch Linux image:

FROM digitallyseamless/archlinux-armv6h

COPY qemu-arm-static /usr/bin/

This image builds qemu-arm into your base image. This is needed in the balena builder so that all your code can be correctly cross compiled for the targeted ARM architecture.

Step 3:

From this point, we are going to dive into Docker land, so make sure you are familiar with Docker commands. If you are unsure of building Docker images, start with a little reading from over here

From the terminal cd into the folder you cloned in step 2 and run:

docker build -t myDockerHubName/myNewBaseImageName .

Where myDockerHubName is your account name on Docker Hub and myNewBaseImageName is some fancy name you came up with for your new base image.

Note: The period . at the end of this command is important!!

This will take a short while to pull down the image from Docker Hub and build it. Once it is finished you should be able to see it in your Docker images list by doing:

docker images

Step 4:

Again from the terminal run:

docker push myDockerHubName/myNewBaseImageName

After a short while you should have your new base image reading and waiting on Docker Hub.

Step 5:

Make a new balena project that uses your new image as its base. It could look like this in the case of the Arch Linux ARM example:

FROM shaunmulligan/arch-armv6h-resin

RUN pacman -Sy --noconfirm python2 python2-flask dropbear

RUN dropbearkey -t dss -f etc/dropbear/dropbear_dss_host_key
RUN dropbearkey -t rsa -f /etc/dropbear/dropbear_rsa_host_key

COPY . /app

CMD ["bash", "/app/"]

This is from my demo project, which just launches an ssh daemon and small hello world python-flask server on boot.

One pretty cool consequence of this is that users can share their base images, for instance you can now base you balena projects on shaunmulligan/arch-arm6h-resin because it is a public image.

So there you have it. Brand new base images for your balena projects in 4 simple steps (step 5 doesnt really count :P ).