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.

Basic Setup

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.

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.35) 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

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.

Docker Compose

If you'd prefer to add some automation, Docker Compose is a great way to do that. Check out the official Docker Compose documentation, then include this in your services section:

    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: /media/docker/munkireport.env
        volumes:
            - /media/docker/munkireport/local:/var/munkireport/local:rw
        networks:
            - munki
        restart: always
        depends_on:
            - mysql-munkireport

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

As in the prior examples, you'll want to make edits to suit your environment. This example assumes your Docker data is being saved to /media/docker, and that you have a munki Docker network. Note that no ports are exposed, as this example is paired with a reverse proxy / load balancer like Nginx, Caddy, or Traefik.