Server Setup

MunkiReport is a PHP web application, it needs a server that can execute PHP scripts. Setting up a PHP capable webserver is beyond these instructions.

Requirements

• Use a supported version of PHP 8. Ensure PHP 8 has the following modules - they are not always bundled:
  • php-mysql
  • php-ldap
  • php-mbstring
• If using MySQL, version 5.7 or higher is recommended.
• (if installing via git) - Composer

Installing MunkiReport

• Pick or create a directory outside the webroot of the server to install the MunkiReport source files. You don't want the source files to be accessible via the webserver. A common location for these files would be /usr/local/munkireport

Option 1 - Download Zip Archive

• Visit https://github.com/munkireport/munkireport-php/releases/latest to download the latest release in zip format. Unzip to the chosen source file directory.

Option 2 - git clone

• Clone the MunkiReport repo into the chosen source file directory:

git clone https://github.com/munkireport/munkireport-php.git

Install and Run Composer

For MunkiReport to install the needed dependencies, composer must be installed. To install, follow the composer installation instructions. Once installed, run:

composer install --no-dev --no-suggest

Note: if you have followed the above linked instructions for a local install of composer, you will need to run specifying the file name, as such:

./composer.phar install --no-dev --no-suggest

Run migrations

The admin must manually trigger a database migration. That can be done two ways:

Note: the first method does not currently work with 3.3.1. Simply continue on to serve the site and run migrations from the Admin panel

• Run the migration script from the munkireport-php folder on the server via CLI

php database/migrate.php

**_Note: beginning with 5.6.0, you should use this command to migrate:

./please migrate

• In the web console access the Admin->Database menu and click the Update button.

Document root

Now you need to make the public folder accessible to the web. There are a couple of ways to achieve that:

Method 1: set the right document root folder

In your webserver configuration file, set [/path/to/munkireport/public] as the document root.

Pros: this is the easiest and safest method.
Cons: you need to be allowed to choose the document root folder, serving multiple apps from subdirectories is harder

Method 2: create a symbolic link

Using the terminal, create a symbolic in your web directory that points to [/path/to/munkireport/public]

For example:

ln -s /usr/local/munkireport/public /var/www/report

Pros: safe and quite easy and allows you to serve MunkiReport from a subdirectory.
Cons: you need to be able to create symbolic links

Method 3: copy the public folder

You can copy the public folder to the web root and change index.php so it can find the MunkiReport source directory:

In index.php:

define('APP_ROOT', dirname(PUBLIC_ROOT) . '/' );

needs to be changed to

define('APP_ROOT', '/path/to/munkireport/' );

Pros: safe and applicable on most hosting services.
Cons: you will need to do this again when upgrading (files in public may have changed)

After you have setup the document root, you should be able to visit your MunkiReport server with a web browser. MunkiReport will complain about a missing config file, but we'll address that in the next section.

Follow the wiki article on Server Configuration to create the needed configuration files. To see more advanced server setups, read the Server Setup Advanced wiki page.

Running MunkiReport from a Subdirectory

MunkiReport should able to detect if it is running from a subdirectory. If automatic detection fails, you can also specify the subdirectory in .env. So if you want to run MunkiReport from http://munki.mysite.org/report/ add the following to .env:

SUBDIRECTORY="/report/"