Install IOTStack on a Mac Mini

Let me help you install IOTStack on a Mac Mini. Why? Just because you can? Well, maybe. The true motivation, however, is that I had an un(der)used late 2012 Mac Mini at home that looked to be perfectly suited to run a few Docker containers.

The IOTStack README introduces the project like this:

IOTstack is a builder for docker-compose to easily make and maintain IoT stacks on the Raspberry Pi.


Indeed, I had previously run, but hardly used, IOTStack on a Raspberry Pi. However, due to the global chip shortage RPis are hard to come by these days. Used ones sell for astronomical sums on second hand sites. The internet is full of articles evaluating Raspberry Pi alternatives. Yet, none mention that you can get excellent second had Mac Minis for little money. But… the IOTStack documentation does not mention how to set it up on alternative hardware.

So, with no Raspberry Pi to spare and no documentation how to install IOTStack on a Mac Mini I was not sure how far I would get. On the other hand, isn’t IOTStack “just” a collection of opinionated Docker Compose recipes that should run on any system that runs Docker?

Install IOTStack on a Mac Mini

macOS preparation

There are number of pieces to this puzzle that you need to install on the Mac Mini before you can start installing IOTStack.

  • Update macOS to the latest available version for the Mac Mini. For the late 2012 model Catalina is the last supported OS version. Sure, there are ways to work around Apple’s policies and install later versions but I saw no need to here.
  • Install Docker (Desktop) but WATCH OUT! The latest supported version for Catalina is 4.15.0. The next version removed support for Catalina without prior notice and no hint in the release notes. Also, I recommend you turn off auto-updates as Docker would otherwise update itself to death.
  • Install Homebrew – the missing package manager for Mac.
  • Using Homebrew install Python (3.x) and virtualenv.
  • Install Git, either standalone or through the Xcode Command Line Tools (again, using Homebrew).
  • IOTStack relies on Whiptail to render dialogs for its visual installation process. Whiptail, however, ist not available for macOS. Hence, what you want to do is create a whiptail alias for dialog which, you guessed it, you install using Homebrew.

Install IOTStack

Finally, time to install IOTStack. On the Pi you would install it into the home folder of the standard pi user. On the Mac I installed it into the home folder of an admin user. Whether admin privileges are required I do not know.

The first steps where smooth sailing.

Then all hell broke loose on my machine. If it works for you then skip ahead.

I had no idea what the root cause for the error(s) was, but I was irritated to see virtualenv mentioning python3.11 in the output – I had installed Python 3.10. Turns out that the virtualenv Homebrew formula depends on Python 3.11, yet when you install the latest stable Python formula you get 3.10. Scrolling through the virtualenv formula’s Git history you realize that the last version still depending on Python 3.10 is 20.16.7. Hence, I had to force install that version, which is a bit of a pain with Homebrew.

Once this was patched, running the IOTStack installer again (./ completed successfully. Please refer to the IOTStack “Getting Started” guide for further details. Note that so far I did not have to patch any of the macOS system libraries or components (as the guide requires for Pi).

Configure containers

I cannot claim that all available IOTStack container recipes work on macOS. However, the ones I need do. The excellent documentation describes all of them in great detail.

Leave a Reply