Docker

Whether you want to test MunkiReport or run it in a production environment, Docker might be the easiest way to accomplish this. The official Docker image for MunkiReport is available on GitHub's Container Registry.

First, check out Docker's documentation for a basic explanation of how Docker works. In a nutshell, you'll be downloading the Adminer, MunkiReport, and MariaDB images from GitHub and Docker Hub. You'll then be creating containers from those images, which contain your customizations - which would include where you'd want the data to be saved on disk, your environment variables (what you'd otherwise specify in your env file), etc. Images are immutable, but containers are not.

It's important to note that you can create Docker containers using both the docker run and docker compose commands. The docker run command is great for getting started and learning the concepts, but docker compose is much better for running a container long-term.

Synology NAS note

Please note, MunkiReport's Docker image requires a kernel version higher than 3.16. To check this system requirement, enable SSH in DSM, log in to your NAS via SSH, and run this command:

uname -r

If supported, you'll see a number higher than 3.16.

Test Setup with Docker Run

If you're testing Docker or just trying to get comfortable with the concepts, docker run is a great way to learn how to use Docker. As mentioned below, the best way to run Docker is by installing Docker Engine on Linux, but if you don't want to invest the time in installing Linux, Docker Desktop on macOS should do fine.

As mentioned, first, install Docker Engine (if you're using Linux) or Docker Desktop (if you're using any other OS). Be sure to launch it and install any dependencies.

Next, open up the Terminal, and run this command:

/bin/mkdir /Users/Shared/munkireport-db

This will create a folder for your MunkiReport SQLite database.

Next, run this command:

docker run -d --name="munkireport" \
  -e "SITENAME=I Love MunkiReport" \
  -e "MODULES=applications, ard, bluetooth, certificate, disk_report, displays_info, extensions, filevault_status, fonts, ibridge, installhistory, inventory, localadmin, managedinstalls, munkireport, network, power, printer, profile, security, usb, user_sessions, warranty" \
  -v /Users/Shared/munkireport-db:/var/munkireport/app/db \
  -p 8181:80 \
  ghcr.io/munkireport/munkireport-php:v5.8.0

This will download the Docker image for MunkiReport to your computer, then create a container with the customizations you've specified above. Once it's finished, you can open a web browser and go to http://127.0.0.1:8181 and view your MunkiReport installation. It'll also be available at your Mac's IP address (for example: http://192.168.1.101:8181) if you want to visit it from another device.

That was really quick! But what if you want to run this in a way that's easier to maintain? Please read on, for how to set this up with docker compose instead...

Production Setup with Docker Compose

If you're looking to run your MunkiReport container long-term, docker compose is the way to go. If you'd like more information about docker compose, see the official documentation.

Although you can run Docker on macOS, Windows, and Linux, if you're planning to use Docker in production, it's recommended that you use Linux and avoid using Docker Desktop. Docker Desktop utilizes a Linux VM behind the scenes, which uses extra resources and can complicate forwarding ports. As weird as it sounds, you'll have an easier time with Docker Engine on Linux. Ubuntu is fine, though most flavors should do the job.

Before getting started with MunkiReport and docker compose, follow Docker's instructions for installing Docker Engine on Linux.

Once you have Docker Engine installed, create a directory for storing all of your stuff. We'll make a directory at the root of the drive, then make a couple of folders for MunkiReport and MariaDB:

sudo mkdir -p /data/docker/{munkireport,mariadb-munkireport}

Also, make a few files for your docker compose yaml file and your env files:

sudo touch /data/docker/{__docker-compose.yml,munkireport.env,mariadb-munkireport.env}

In fact, let's edit those right now:

sudo nano /data/docker/__docker-compose.yml

Populate the yaml file with this:

networks:
  munki:
    name: munki
    driver: bridge

services:

    adminer:
        container_name: adminer
        image: adminer
        # https://hub.docker.com/_/adminer/
        networks:
            - munki
        ports:
            - "8080:8080"
        restart: always

    munkireport:
        container_name: munkireport
        image: ghcr.io/munkireport/munkireport-php:v5.8.0
        # https://github.com/munkireport/munkireport-php/pkgs/container/munkireport-php
        env_file: /data/docker/munkireport.env
        volumes:
            - /data/docker/munkireport/local:/var/munkireport/local:rw
        networks:
            - munki
        ports:
            - "8181:80"
        restart: always
        depends_on:
            - mariadb-munkireport

    mariadb-munkireport:
        container_name: mariadb-munkireport
        image: mariadb:11.0
        # https://hub.docker.com/_/mariadb/
        env_file: /data/docker/mariadb-munkireport.env
        user: "1000:1000"
        volumes:
            - /data/docker/mariadb-munkireport:/var/lib/mysql:rw
        networks:
            - munki
        restart: always

Edit the MariaDB config to include a root password:

sudo nano /data/docker/mariadb-munkireport.env

MARIADB_ROOT_PASSWORD=YOURSUPERSECRETPASSWORD

Edit your MunkiReport config to include your MariaDB root password, as well as anything else you want to specify. Here's an example:

sudo nano /data/docker/munkireport.env

SITENAME=I Love MunkiReport

CONNECTION_DRIVER=mysql
CONNECTION_HOST=mariadb-munkireport
CONNECTION_PORT=3306
CONNECTION_DATABASE=munkireport
CONNECTION_USERNAME=root
CONNECTION_PASSWORD=YOURSUPERSECRETPASSWORD
CONNECTION_CHARSET=utf8mb4
CONNECTION_COLLATION=utf8mb4_unicode_ci
CONNECTION_STRICT=TRUE
CONNECTION_ENGINE=InnoDB

MODULES=munkireport,managedinstalls,disk_report

Now, create a script for building your Docker containers:

sudo mkdir -p /data/scripts

Populate it:

sudo nano /data/scripts/update_docker_containers.sh

#!/bin/bash

# This updates your Docker images
/usr/bin/docker compose -f "/data/docker/__docker-compose.yml" pull

# This rebuilds your Docker containers to match the yaml file. Be careful, as it deletes any containers not mentioned in your yaml file!
/usr/bin/docker compose -f "/data/docker/__docker-compose.yml" up -d --remove-orphans

# This deletes any Docker images that are old/unused.
/usr/bin/docker image prune -a -f

exit

Before running the script you need to set the permissions on the directory that's being mounted as /var/lib/mysql on the MariaDB container. We're setting the user and group both to UID/GID 1000 in the docker-compose file above, so:

sudo chown 1000:1000 /data/docker/mariadb-munkireport

Now, run your script:

sudo /data/scripts/update_docker_containers.sh

You'll see a bunch of text fly by, and hopefully you'll see your Adminer, MunkiReport, and MariaDB containers are all running. Visit your Adminer container to create your database:

http://127.0.0.1:8080

(you'll want to specify the hostname as mariadb-munkireport, the user as root, and the password you selected above)

Be sure to create a munkireport database.

Lastly, visit your MunkiReport instance to get started:

http://127.0.0.1:8181

You should be able to run migrations from the Admin menu, populating the MariaDB database in the process.

If you can reach your MunkiReport instance via the LAN IP (example: http://192.168.1.100:8181), you can point your clients there. However, if you'd prefer to use HTTPS and a subdomain, please see the Reverse Proxies and Load Balancers page on how to accomplish that.

Some notes:

• MariaDB permissions are set up for user 1000. You can check your UID by running id.
• As you can see, only Adminer and MunkiReport have ports exposed. Because all three containers are on the munki network, they can all talk to each other. However, it's not possible to reach the MariaDB container from anything other than Adminer or MunkiReport (which is fine).
• If you want to keep Adminer and MariaDB up to date, just set cron to run /data/scripts/update_docker_containers.sh regularly, like overnight.
• If you want to update MunkiReport, just change v5.8.0 to a new number, save the yaml file, and run /data/scripts/update_docker_containers.sh. That's it!

Creating your own Docker Image with Custom Modules

This is one method of maintaining your docker image with custom modules. Some may prefer to maintain and update modules via composer instead of tracking down git branches and cloning. We can create our very own docker image of MunkiReport containing third-party modules as well as updating any core modules.

In this example, we will just be building an image on our test server and then running it. It will be up to the reader to further scale this via docker hub or other docker image platform.

On your dev/test server, create a empty directory. We will just call this /var/docker/mr in this case.

Inside this directory create a file called Dockerfile and lets put in the following. This has a couple modules as an example.

FROM ghcr.io/munkireport/munkireport-php:v5.8.0

RUN composer require joncrain/manifests:^3.0 tuxudo/kernel_panics:^3.0 tuxudo/launchdaemons:^3.0 tuxudo/ms_office:^3.0 tuxudo/nudge:^2.0 tuxudo/browser_extensions:^3.0 tuxudo/icloud:^3.0 && \
    composer update --no-dev

The file above is referencing the official MunkiReport docker image (version 5.8 currently) and then running commands to require and update composer with the third-party modules we want. We will build our image by running the following from within that directory:

docker build -t munkireport --progress plain --no-cache .

We now have a docker image called munkireport on this local dev/testing machine. You may now simply update your docker run or docker-compose.yml to reference this image. Mapping a volume to /var/munkireport/custom-modules if you had been doing so before is no longer needed and can be removed.

Just like running docker with the official image we must make sure we include the module vendors in our environment variables. (env file or docker-compose.yml):

MODULE_SEARCH_PATHS=/var/munkireport/vendor/tuxudo,/var/munkireport/vendor/joncrain

When you run this new image please be sure to check for any database migrations that may be needed. You will also want to pull a new client to distribute.

If you want to add new modules or get updated core modules put into your image, simply edit the Dockerfile if needed and run the docker build command from above again. You will then want to recreate your docker container. Simple as that!

MunkiReport in Microsoft Azure

If you want to run MunkiReport in Azure, this script will help you set up all of the above stuff (plus HTTPS and a custom URL) automatically.