ESP8266: using Docker to setup the build tool chain the easy way

When you get started with wonderful world of the ESP8266 your first step might have been to play around with the AT command firmware. Then you might have chosen one of the pre-built multi purpose firmwares, such as the NodeMCU or the NodeLua image. Then, the next logical step is to build a firmware yourself. But honestly, I was a bit afraid of this one, since it seemed all very Linux oriented and I wanted to run it on my Mac. Until I found zoobab’s Dockerfile. I had heard about Docker before but never used it myself. This tutorial will walk you through the whole process from “Nada to Tadaa!”

1. Install docker

Since docker is only truly native on Linux you might want to use another tool to get docker running under Windows and Mac OS X. It’s called boot2docker and uses a tiny Linux image running inside VirtualBox to get docker running on your non-linux OS. 
Go to and download the version for your operating system and run the installer.
Note: while this worked without any problems on my Mac I had some (still unsolved) issues on Windows 7. Probably they were caused by pre-installed Git and VirtualBox. If possible remove these two applications before you install boot2docker and let the installer take care of re-installing them.
To test the successful installation run:

docker run hello-world

from the boot2docker command line.

2. Create the docker container

If you didn’t have git before starting this walkthrough you will have now: boot2docker should have installed it. That’s why you can now execute

git clone
cd esp8266-docker-buildbox/
docker build -t local/buildbox .

This last step might take a while (or two): in my case it took almost 20 minutes. But the good thing is that you’ll only have to do it once.

3. Run the docker container and compile your first firmware

Now it’s time to start the container:

docker run -i -t local/buildbox /bin/bash

Will start the container. Now you get to compile your first firmware by

su - esp8266
cd source-code-examples/blinky/
If everything worked out you’ll have to files in the firmware folder: 0x00000.bin and 0x40000.bin! Congratulations, you just built your first ESP8266!

Note: Now you’d still have to get the images somehow to your ESP8266. I will update this post shortly and describe how you can do that…

Posted by Daniel Eichhorn

Daniel Eichhorn is a software engineer and an enthusiastic maker. He loves working on projects related to the Internet of Things, electronics, and embedded software. He owns two 3D printers: a Creality Ender 3 V2 and an Elegoo Mars 3. In 2018, he co-founded ThingPulse along with Marcel Stör. Together, they develop IoT hardware and distribute it to various locations around the world.


  1. Hi, I spoke too soon… I was forgetting to start the container, now everything works!
    I am really a newbie about the ESP8266, so maybe the question is silly.
    How does the debugging work in this environment ? Can I do printfs ?

  2. Have you tried this command to pass on the /dev/ttyUSB0 inside the container?

    root@mybox# docker run –privileged -v=/dev/ttyUSB0:/dev/tty-from-host -i -t zoobab/esp8266-docker-buildbox /bin/bash

    Nice to see you made some improvements, I need to get back to ESP8266 and add more examples of C code people can push out of the box on the device.

Leave a Reply