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 MySQL 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. Therefore, we'll be covering docker compose (with the docker run command at the end, if you're curious). For more information about docker compose, see the official documentation.

Basic Setup with Docker Compose

Although you can run Docker on macOS, Windows, and Linux, it's recommended that you use Linux. On macOS and Windows, Docker 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 Linux. Ubuntu is fine, though most flavors should do the job.

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

Once you have Docker 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 MySQL:

sudo mkdir -p /data/docker/{munkireport,mysql-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,mysql-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.7.1
        # 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:
            - mysql-munkireport

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

Edit the MySQL config to include a root password:

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

MYSQL_ROOT_PASSWORD=YOURSUPERSECRETPASSWORD

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

sudo nano /data/docker/munkireport.env

CONNECTION_DRIVER=mysql
CONNECTION_HOST=mysql-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 MySQL-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/mysql-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 MySQL 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 mysql-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 MySQL 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:

• MySQL 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 MySQL container from anything other than Adminer or MunkiReport (which is fine).
• If you want to keep Adminer and MySQL 5.7 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.7.1 to a new number, save the yaml file, and run /data/scripts/update_docker_containers.sh. That's it!

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.

Basic Setup with Docker Run

Since you will want the data to persist between docker runs, the database will need to reside outside of the MunkiReport Docker container.

First create a persistent volume for the database data to be stored in. The command below creates a docker volume that binds to a directory on the host machine. This only has to be done once on the host:

docker volume create --name munkireport-db

Start the MunkReport container as follows, referencing the volume created in the previous step:

docker run -d --name="munkireport" \
  -v munkireport-db:/var/munkireport/app/db \
  -p 80:80 \
  ghcr.io/munkireport/munkireport-php:v5.7.1

Breaking down the command above:

• docker run - Run a command in a new container.
• -d - Starts the container in detached mode.
• --name="munkireport" - Gives the container a friendly name for referencing with other docker commands.
• -v munkireport-db:/var/munkireport/app/db - Bind mount a volume: The docker volume will be bound to the directory /var/munkireport/app/db within the container. Database data within the container will be read and written back to the docker volume instead of stored within the container.
• -p 80:80 - Binds port 80 on the host to port 80 of the container. This allows for connection to the host on port 80 to reach the MunkiReport container.
• ghcr.io/munkireport/munkireport-php:v5.7.1 - Docker will pull and run the munkireport-php docker container that is tagged with the version at the end. Change this tag to run a different version of the munkireport-php docker container.

This basic setup will use a SQLite database that is perfect for testing. You should now be able to open a browser and access MunkiReport on port 80 of your host machine.

Additionally, you can inspect the docker volume that contains the database by running the following command:

docker volume inspect munkireport-db

Which should output something similar to the following:

[
    {
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/munkireport-db/_data",
        "Name": "munkireport-db",
        "Options": {},
        "Scope": "local"
    }
]

Your database data will be contained in the directory listed by "Mountpoint": The file created in the directory in the listed Mountpoint will be called db.sqlite and it needs to be writeable by the user www-data indside the container (which has UID=33), so it either needs to be owned by UID 33 or be world writeable (never recommended), so the easiest solution is to chown 33 /var/lib/docker/volumes/munkireport-db/_data/db.sqlite in the host system. Might need to run chown 33 /var/munkireport/storage/logs/auth.log inside the container as well, to make it writeable by the www-data user.

NOTE: In the Docker cli you can see where your database is and who owns it to fix any initial setup issues.

# ls -lh app/db -rw-r--r-- 1 root root 3.5M Feb 17 20:29 db.sqlite

If the owner is not www-data then you can fix this.

id www-data uid=33(www-data) gid=33(www-data) groups=33(www-data)

chown 33 app/db/db.sqlite

ls -lh app/db -rw-r--r-- 1 www-data root 3.5M Feb 17 20:29 db.sqlite

Configuring MunkiReport Settings

MunkiReport is configured using environmental variables. Below are a few examples to start out with:

• SITENAME: The name of your site, displayed in the title.
• MODULES: A comma delimited list of enabled modules.
• AUTH_METHODS: A comma delimited list of authentication methods.

When running MunkiReport in docker, you can start the container with the environmental variables by using the -e flag, like in the example below:

docker run -d --name="munkireport" \
  -e "SITENAME=I ❤️ 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 munkireport-db:/var/munkireport/app/db \
  -p 80:80 \
  ghcr.io/munkireport/munkireport-php:v5.7.1

See also MunkiReport Configuration Variables

Additionally, you can use --env-file flag to reference a file containing a list of environmental variables. This can be useful to reduce the length of the docker run command. An example .env file is provided in the main munkireport-php repo. Please note that when using --env-file you should not use quotes around values as the quotes get passed to the container due to how Docker CLI functions. To fix this in the provided example file, run the following command:

/usr/bin/sed 's/\"//g' .env.example > .env

Note that changing any env variables requires you to rebuild your container before they'll take effect. You can use a tool like Docker Compose (see below) to make the process easier.

Additional Setup Examples

MunkiReport can also be used with an external MySQL database, but that can also be run in docker! Below is a example of the docker run commands to use a MySQL database container:

As in the previous example, we will start by creating a persistent volume for the database. This only has to be done once on the host:

docker volume create --name munkireport-db

Next start the MySQL container using the command below. You need to specify version 5 of MySQL due to a change in the default authentication plugin that breaks required functionality. Again, once you have a working setup, you may want to change the tag to a specific version (example mysql:5.7.38-debian) to prevent MySQL from being updated when the container is restarted, allowing you to plan for upgrades.:

docker run -d \
  --name="mysql" \
  -v=munkireport-db:/var/lib/mysql \
  -p 3306:3306 \
  -e "MYSQL_ROOT_PASSWORD=root" \
  -e "MYSQL_DATABASE=munkireport" \
  -e "MYSQL_USER=admin" \
  -e "MYSQL_PASSWORD=admin" \
  mysql:5.7-debian

Next start the MunkReport container as follows, referencing the volume created in the previous step, and passing the environmental variables to use the MySQL database instead of the default SQLite database. Note that you will need to fill in your docker host IP:

docker run -d --name="munkireport" \
  -v munkireport-db:/var/munkireport/app/db \
  -p 80:80 \
  -e "CONNECTION_DRIVER=mysql" \
  -e "CONNECTION_HOST=HOST_IP_HERE" \
  -e "CONNECTION_PORT=3306" \
  -e "CONNECTION_DATABASE=munkireport" \
  -e "CONNECTION_USERNAME=admin" \
  -e "CONNECTION_PASSWORD=admin" \
  ghcr.io/munkireport/munkireport-php:v5.7.1

MunkiReport will now be using MySQL which is also running in a docker container, however MySQL will be storing the database on the host using the docker volume "munkireport-db", so the data will persist.