Ajeet Raina Docker Captain, ARM Innovator & Docker Bangalore Community Leader.

Building a minimalistic LinuxKit OS on Raspberry Pi 3 using Moby

3 min read

LinuxKit GITHUB repository recently crossed 3495 stars, forked around 410+ times and added 80+ contributors. Just 7 months old project and it has already gained lot of momentum across the Moby community. In case you’re new, LinuxKit is the first use case for the Moby Project, which is basically a toolkit used for building secure, portable, and lean operating systems for containers. It uses YAML files to describe the complete system, and Moby uses it to assemble the boot image and verify the signature. LinuxKit uses the Moby tool for image builds, and the LinuxKit tool for pushing and running VM images.

In the last Dockercon 2017 EU, Docker Inc. announced the latest additions which includes – 

  • Support for arm64 architecture
  • Improved platform support (Azure, IBM Bluemix, AWS, Google Cloud Platform, VMware, Hyper-V, Packets.net etc.)
  • Upcoming Kubernetes support (I tried it and believe me it was a great experience)
  • Linux containers on Windows (LCOW) preview support
  • Multi-arch build system
  • Fully immutable system images
  • Namespace sharing
  • Support for the latest Linux kernels

LinuxKit today supports building & booting images on a Raspberry Pi 3 using the mainline arm64 bit kernels. Under this blog post, I will show how to build Linuxkit OS on Raspberry Pi 3.


  1. OpenSUSE 42.2 Leap 
  2. Raspberry Pi 3
  3. SD card
  4. Win32 Disk Imager 
  5. SD Formatter(Windows Client) or Etcher(for MacOS)
[PLEASE NOTE – In case you’re trying to build LinuxKit on Raspbian OS running on your Pi box, it is NOT going to work. Reason – There is no 32-bit kernel built for Linuxkit. As of today, only 64-bit based kernel is available for LinuxKit OS. If you’re planning to build Linuxkit with 32-bit kernel, feel free to share your findings.I picked up openSUSE OS as it has a arm64 flash for Raspberry Pi 3 ]

Early this year I wrote a blog on how to test-Drive Docker 1.12 on first 64-bit ARM OpenSUSE running on Raspberry Pi 3. You can refer it to get started.

  1. Download OpenSUSE 42.2 Leap from this link and follow the blog thoroughly to get it ready on SD card.



    2. Install Docker on OpenSUSE 42.2 

By default, OpenSUSE Leap comes with Docker 1.12 edition. Though it is pretty old, we can still build LinuxKit on the operating system. Ensure that Docker is up and running on your Raspberry Pi 3 box:


$systemctl restart docker 



      3.  Building Moby tool on Raspberry Pi

You will need Go version 1.8 atleast to get Moby and Linuxkit built on OpenSUSE 11.3.


$go get -u github.com/moby/tool/cmd/moby



      4.  Building LinuxKit 



linux:~/linuxkit # go get -u github.com/linuxkit/linuxkit/src/cmd/linuxkit

# github.com/linuxkit/linuxkit/src/cmd/linuxkit

/usr/lib64/go/1.8/pkg/tool/linux_arm64/link: running gcc failed: fork/exec /usr/bin/gcc: cannot allocate memory


In case you encounter the above error message, you need to fix this issue by adding more space to swap partition.

Step:1 – Create a 1GB File

We use the DD command to create the 1G file basically writing “0″ into the file swap_1 in the “/” file system.


linux:~/linuxkit # dd if=/dev/zero of=/swap_1 bs=1024 count=1000000

1000000+0 records in

1000000+0 records out

1024000000 bytes (1.0 GB, 977 MiB) copied, 64.4194 s, 15.9 MB/s


Step-2 – Setting up File as a swap area.


linux:~/linuxkit # mkswap /swap_1

mkswap: /swap_1: insecure permissions 0644, 0600 suggested.

Setting up swapspace version 1, size = 976.6 MiB (1023995904 bytes)

no label, UUID=e2f577a5-ff87-40ee-adfc-78e8feef3a36


Step-3 – Enabling Swap File for system to start paging physical memory pages onto it.


linux:~/linuxkit # swapon /swap_1

swapon: /swap_1: insecure permissions 0644, 0600 suggested.


Step-4: Verify the new free memory:


linux:~/linuxkit # free -tom

             total       used       free     shared    buffers     cached

Mem:           785        745         40          3          1        688

Swap:         1462         65       1396

Total:        2247        810       1437



Now, you can build up LinuxKit tool flawlessly. Once installed, you can verify it with the below command:


Let us build minimal LinuxKit OS using the below command:


$moby build -format rpi3 minimal.yml




Now it’s time to convert minimal.tar into ISO format. You can leverage the following tool:


bash-3.2# hdiutil makehybrid -o /Users/ajeetraina/Desktop/linuxkit.iso minimal -iso -joliet

Creating hybrid image…


By now, you should be able to boot the minimal LinuxKit ISO on your Raspberry Pi system via uboot tool. It can also be directly be extracted onto a FAT32 formatted SD card to boot your Raspberry Pi. 

Did you find this blog helpful?  Feel free to share your experience. Get in touch @ajeetsraina

If you are looking out for contribution/discussion, join me at Docker Community Slack Channel.


Have Queries? Join https://launchpass.com/collabnix

Ajeet Raina Docker Captain, ARM Innovator & Docker Bangalore Community Leader.

Under the Hood: Demystifying Docker For Mac CE Edition

Docker is a full development platform for creating containerized apps, and Docker for Mac is the most efficient way to start and run Docker...
Ajeet Raina
4 min read

Top 5 Exclusive Features of Docker For Mac That…

  Docker for Mac 18.04.0 CE Edge Release went GA early last month. This was the first time Kubernetes version 1.9.6 & Docker Compose...
Ajeet Raina
5 min read

Top 10 Reasons why LinuxKit is better than the…

  “LinuxKit is NOT designed with an intention to replace any of traditional OS like Alpine, Ubuntu, Red Hat etc. It is an open-source...
Ajeet Raina
7 min read

2 Replies to “Building a minimalistic LinuxKit OS on Raspberry Pi 3…”

Leave a Reply

Your email address will not be published.