Configuring reposado & margarita with Docker on a Mac

There are already great guides for how to configure reposado & margarita (the reposado web front-end) on Ubuntu and on Mac.  However, neither of these setups gave me everything I wanted in my environment.

Justifications for Docker on a Mac:

  • Too many web servers:  Despite wanting this to run on a Linux server, I couldn’t justify spinning up yet another dedicated web server in our small environment.
  • Available Hardware & Storage:  Unless you are going to manage which individual Apple Software Update catalogs is mirrored by reposado, you’re going to need at least 1TB of storage, as completing a full repo_sync of all available catalogs (as of this writing) takes up a whopping 462GB of storage.  Luckily (or unluckily, depending on your POV), we had a severely underutilized Mac Mini that was being used solely as our internal Apple Service Toolkit (AST) NetBoot server and a spare 2TB external USB3 hard drive.
  • Operating System:  Because the Mac Mini I had available was several macOS versions back and I wanted to avoid having to upgrade the OS all the way to High Sierra (this is due to the fact the currently available macOS Server app – 5.6.1 – requires 10.13.4 to run), I wasn’t able to get pip or flask installed (required for margarita) due to errors resulting from using TLSV1 when attempting to download this software.
  • Nginx:  While I haven’t worked too much with Nginx up to this point, the performance benefits when under heavy loads are notably better than Apache.

Ultimately, I discovered a single Docker container that combined both reposado and margarita, allowed basic authentication in order to access the margarita front-end, would run on our older version of macOS, and by default can set various settings pertaining to reposado and margarita.

Big shout-out to @sphen for the Docker image!

See more details below the jump.

1) Install Docker

Grab the latest community release version of Docker and install it.  If you don’t have a Docker Hub account, that’s OK, you don’t need one (even though Docker will ask you to sign in or create one).

2) Create Local reposado Folders

Create the local folders on your Mac mini that your Docker container will use to store the reposado html and metadata content:

mkdir -p /path/to/reposado/html

mkdir -p /path/to/reposado/metadata

3) Pull the Combined reposado & margarita Docker Image

Open Terminal and run:

docker pull sphen/reposado

4) Create the Docker Container

Create the container by running:

docker run -d --name reposado -v /path/to/reposado/html:/reposado/html -v /path/to/reposado/metadata:/reposado/metadata -p (hostreposadolisteningport):(containerreposadolisteningport) -p (hostmargaritalisteningport):(containermargaritalisteningport) -e LOCALCATALOGURLBASE='http://(hostnameORserverip):(reposadolisteningport)' -e PORT=(reposadolisteningport) -e LISTEN_PORT=(margaritalisteningport) -e HUMANREADABLESIZES=true -e USERNAME=(username) -e PASSWORD='(password)' --restart always sphen/reposado
  • --name reposado: the name of the Docker container
  • -v /path/to/reposado/html:/reposado/html: the path on the local machine containing the reposado html folder and the path to map it to in the container, which must be /reposado/html
  • -v /path/to/reposado/metadata:/reposado/metadata: the path on the local machine containing the reposado metadata folder and the path to map it to in the container, which must be /reposado/metadata
  • -p (hostreposadolisteningport):(containerreposadolisteningport): bind the desired port on the host to the desired container port for reposado
  • -p (hostmargaritalisteningport):(containermargaritalisteningport): bind the desired port on the host to the desired container port for margarita
  • -e LOCALCATALOGURLBASE='http://(hostnameORserverip):(hostreposadolisteningport)': environment variable to set the reposado preferences to use the given address and port
  • -e PORT=(reposadolisteningport): environment variable to set the port for reposado to use for serving updates
  • -e LISTEN_PORT=(margaritalisteningport): environment variable to set the port for margarita to use for the web front-end
  • -e HUMANREADABLESIZES=true: environment variable to set the reposado preferences.plist HumanReadableSizes key to true to make the downloading informational output to be more friendly
  • -e USERNAME=(username): environment variable to set the username to be used to login to margarita
  • -e PASSWORD=(password): environment variable to set the password to be used to login to margarita
  • --restart always: whenever docker restarts, automatically restart the container as well
  • sphen/reposado: the image to use for creating the container

By default, if you choose to not specify a PORT or LISTEN_PORT environment variables in your command, port 8080 will be used for reposado and port 8089 will be used for margarita.  Just make sure whatever ports you specify for PORT and LISTEN_PORT is what you use for (containerreposadolisteningport) and ​(containermargaritalisteningport).

If you want to verify your reposado settings, run the following to read the preferences.plist file in your container:

docker exec reposado cat /reposado/code/preferences.plist

No need to run repoutil --configure as these preferences are already configured.

5) Verify margarita Login

Open a browser and navigate to the hostname or IP address of your Mac mini with the port you specified for margarita.


Enter the username and password you specified.

6) Complete Your First repo_sync

With your Docker container created and margarita login verified, it’s time to run your first repo_sync!  All of the reposado commands can be found in the /reposado/code directory in the container.

To do this run:

docker exec reposado /reposado/code/repo_sync

The first sync will take several hours …

By default, reposado will sync all available software update catalogs from Apple, and why I use an external 2TB hard drive for this.

Note: do not be alarmed if you do not see any products listed in margarita immediately.  This will not populate until at least one Apple software update catalog has fully downloaded.

7) Schedule Future repo_syncs

To have your Mac mini automatically run a repo_sync, you can use a LaunchDaemon to run at a desired interval.  Below is one which will run every day at 5 am and which logs output to a local file.

Update: Originally I had not specified a full path to the docker binary, but this is needed in the daemon to run correctly.

Copy your LaunchDaemon to /Library/LaunchDaemons, give it 644 permissions, and set the owner to root:wheel.

chmod 644 /Library/LaunchDaemons/com.yourorg.reposado-reposync.plist

chown root:wheel /Library/LaunchDaemons/com.yourorg.reposado-reposync.plist

Lastly, load your LaunchDaemon.

sudo launchctl load -w /Library/LaunchDaemons/com.yourorg.reposado-reposync.plist

Verify LaunchDaemon Run

To verify your repo_sync ran at the desired time, check the log file specified in your LaunchDaemon.

8) Point Macs to Reposado

With your reposado Docker container setup, you can point your Macs to it.  You can do this by following the reposado docs here.

By default however, the sphen/reposado container is configured to perform URL rewrites.  So, rather than needing to point your Macs running 10.12 to the corresponding catalog – http://youreposadoserver/content/catalogs/others/index-10.12-10.11-10.10-10.9-mountainlion-lion-snowleopard-leopard.merged-1_<reposadobranch&gt;.sucatalog – you could instead point them to the generic catalog – http://yourreposadoserver/index_<branchname&gt;.sucatalog.

Reposado will handle redirecting the machine to the correct catalog based on the macOS version.  Simply define the branch you want your machines to use.


With minimal effort and whatever Mac hardware resources you have available, you can spin up a local Apple software update server with reposado, even on older macOS software.  The result is being able to manage and deploy software updates within your own environment, and also continue to deploy older versions of software that Apple marks as deprecated.

For info on how to setup your Macs to point to your local reposado server for Apple software updates, as well as how to clean out deprecated products you no longer wish to maintain, see the reposado docs.




Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s