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.

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.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. Save this as docker-compose.yml:

networks:
  munki:
    name: munki
    driver: bridge

services:

    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

Some things to change in this example:

• We're assuming your persistent data is being saved to /media/docker. If you have a different path, change that part.
• We're also assuming that your env files are also in /media/docker. Your env files contain your environment variables, so you don't need to clutter your Docker Compose file.
• MySQL permissions are set up for user 1000. You can check your UID by running id.
• There are no ports exposed for either container. That's fine for MySQL (since only MunkiReport will likely need to access it), but to reach your MunkiReport container, you'll need to expose some ports, or use a reverse proxy / load balancer like Nginx, Caddy, or Traefik

Once you're happy with your docker-compose.yml file, just run these commands:

# This updates your Docker images
/usr/bin/docker compose -f "/media/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 "/media/docker/docker-compose.yml" up -d --remove-orphans

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

Of course, adjust for your yaml file's correct path. You can script this to happen overnight if you'd like, which will rebuild your MySQL container as new versions of 5.7 come out. To update MunkiReport, change the version number at the end of image to the version you'd like to run, then run those commands again to download a new image, rebuild your container against the new image, and bring up the updated container.