Building a basic Munki Server on Nginx using Colima and Docker.

I’ve been tinkering with Munki on and off now for probably over a decade. But more recently I’ve been using SimpleMDM’s implementation of Munki.

SimpleMDM removes a lot of the complexity around running your own Munki instance, whilst leaving a reasonable amount of room to tinker with things like pkginfo files… but that lack of complexity also means there are some parts of Munki you just don’t get to work with. I need a refresher I think!

Time to go back to basics

With free time on my hands, I decided I wanted to go back and revisit Munki all over again. So this is my attempt at a guide to get up and running with a home lab setup quickly… I won’t be explaining every component in detail - it’s my opinioned guide to “just-enough” Munki

I’ve also been rewatching Look Around You recently - which has reminded me that good scientists - and this is for a home lab setup after all - should be taking notes, ideally in their copybook, as they go.

If you don’t - you come back to your setup wondering how on earth it all works. As such, these posts are as much for me - to remind me what I’ve built and how I built it, as well as for anyone else…!

Join me!

Demonstration setup

We’ve all gone through this guide right? I know I did, a long time ago. And it’s great. But I wanted to try to build a slightly more “production-like” home lab setup. If you’ve not gone through the demonstration setup before, you probably should. You’ll learn loads. But as I’ve done it before, and think I know what I’m doing (famous last words!) - I wanted to run, or at least manage a slow jog instead before I can walk.

As well as doing my best to mix my metaphors…

It starts with a webserver. As Greg Neagle (the creator of Munki) is fond of saying “A munki server is just a webserver” - so we need a web server. Rather than using Apache on your macOS host (as shown in the demo setup), in production you’d be hosting on a “real” webserver, on a Linux or (even) a Windows server.

I don’t want to spin up another box - but it feels like a good way to pretend we have another server is to use Docker. It also means we can pretend we’re all DevOps experts who know how docker works…

…as with so many of these things, it’s all about knowing enough to be dangerous.

Step One - Docker Desktop…

Or actually - I’d rather not. The thing is, now I’m ex-Thoughtworks, I absolutely qualify for the free tier of Docker Desktop. But the pain and suffering their licencing changes caused me when I was employed as a Mac admin meant I really wanted to avoid Docker Desktop where possible!

The recommended replacement at Thoughtworks was Colima - an open source engine for running container environments. Personally I’d just avoided using Docker on macOS post the licencing change… but it felt like time to learn a little about Colima.

This also involves learning a bit about how to finally use HomeBrew on macOS - something that, again, I have tried to avoid in the past for all kinds of reasons. I mean, brew, it’s not personal, I wasn’t a fan of Fink or MacPorts either… I think this stems from my time at Imperial College, where it just meant a whole world of extra packages to work with, support and potentially debug, and that would sometimes not play nicely with default packages (like python)

But it’s time to get over myself and get Brew installed!

(there are instructions on their website, and, to be honest, a post or two on Brew is probably something else I should do, but it’s made things a lot easier for this homelab setup, as you’ll see in this and future installments)

Once Brew is installed, we can then install Colima:

brew install colima

And we also need to install the docker command line tools too:

brew install docker

Look at us installing tools off the internet! Now we should try to use them properly…

What is Colima anyway?

I mean, the website says it’s short for “Container Runtimes on MacOS” - but all we need to care about is that it’s a virtual machine backend we can run our containers on.

I’m not too fussed about doing anything too clever - let’s just get Colima running so we can start doing some container magic.

colima start -f

This leaves a terminal window running, showing our Colima environment is available. There’s scope for additional tinkering with the colima configuration - but we don’t really need to do so for our lab environment at this point. Tinkering with Colima can be added to the “things to worry about later” category…

Now we need to add some docker containers! For no other reason than it’s popular and has a cool sounding name, let’s run our Munki server on Nginx.

Luckily for us, there’s a helpful getting started guide here which I’m going to borrow from liberally. However, I got stuck at the first hurdle as when I run the initial test command:

docker run -it --rm -d -p 8080:80 --name web nginx

It fails, grumbling about an error getting credentials for docker desktop.

Unable to find image 'nginx:latest' locally  
docker: error getting credentials \- err: exec: "docker-credential-desktop": executable file not found in $PATH, out: \`\`

Ugh. I really don’t want to sign up for Docker desktop just to get this working! (You can though, it’ll save you a lot of pain.)

Workarounds?

I had a thought - what happens if I try to build a local docker container first? So, if I create a dockerfile that doesn’t really do anything, and just contains:

FROM nginx:latest

Then - from the same directory, run:

docker build . 

(yes, that’s a full stop - and it’s important - it means “use the dockerfile in this directory”) Docker dutifully pulls down and builds the container specified, and stores it locally.

Now - try running that previous docker run command

docker run -it --rm -d -p 8080:80 --name web nginx

It should run with no errors, and you too can open a browser on your Mac and visit http:// localhost:8080 to see a welcome page.

So we have a:

• daemonised (running in the background) web server, (the -d option)
• Sending http requests on port 8080 on your host Mac to port 80 of the container (the -p 80:8080 part)
• using the nginx image
• with a name we’ve assigned to it - web

So we have a webserver, but it’s not a munki server… (yet)

We should probably fix that. We want to add Munki content to our server. And we can do that with something called a volume mount. We’ll need to create a local folder on the Mac for our repo - mine lives in:

~/docker/nginx/

In the ~/docker/nginx directory we can create the required folders - so from the Munki setup guide:

mkdir munki_repo  
mkdir munki_repo/catalogs  
mkdir munki_repo/icons  
mkdir munki_repo/manifests  
mkdir munki_repo/pkgs  
mkdir munki_repo/pkgsinfo

Good stuff. Now we need to make these folders available to our docker container. First we need to stop the running container

docker stop web

Now to launch it again - but including our new Munki repo stuff

docker run -it --rm -d -p 8080:80 --name munki -v ~/docker/nginx:/usr/share/nginx/html nginx

Note: I’ve renamed the container from the bland “web” to the slightly more descriptive “munki” - and we’ve added our volume mount with the -v option.

So - our local folder is being mapped to the ngnix folder in the container - /usr/share/nginx/html

So - all being well, we’re running an nginx webserver on port 8080 - ready to use with Munki, it just doesn’t actually contain any Munki content. We can check on our running container with:

docker ps

There it is:

If you just can’t wait to get a package imported into our new munki repo - please do follow along with the official guide here - substituting the path to our local munki repo - so, in my case it’s file:///Users/steve/docker/nginx/munki_repo

But that’s no fun! The goal of this series of posts is creating a “prod-like” setup for my home lab. In production most folks are using autopkg… to check for software and add it to a munki repo automatically. That’s what I want to do here too.

So join me next time for the next exciting installment - when we jump ahead, very much running before we can walk - automating populating our Munki Repo with autopkg.