Setting up a dev environment

To ease developing features for Munkireport, it is advised to set up a local development environment where you can test your code or the code written by others. The easiest way to do that is to run MunkiReport on your own Mac using git and the built-in PHP webserver.

Filesystem (macOS)

The default filesystem on macOS is case insensitive and this has caused problems in the past when files are renamed. So for developers it's advised to add another APFS volume which is Case-sensitive using Disk Utility (or the diskutil command line tool diskutil apfs addVolume disk1 'Case-sensitive APFS' Development ) You will end up with a case-sensitive volume that you can use to check out the MunkiReport sources.

git

Although git is not necessary to develop for MunkiReport, it makes a lot of tasks easier. By default git is not installed on macOS, but there's a stub git command which prompts the user to install the 'Commandline Developer Tools'. Otherwise you can run xcode-select --install to install the Developer Tools.

Checking out the MunkiReport sources

With git in place we can check out the MunkiReport sources:

# Change to the place where you want to install MunkiReport
cd /Volumes/Development 
# Clone MunkiReport
git clone https://github.com/munkireport/munkireport-php.git
# Step into the source directory
cd munkireport-php
# Switch to the development branch
git checkout wip 

composer

MunkiReport dependencies are managed by composer. This is a pretty large PHP script that is not included in the MunkiReport sources, but there's a handy script that will download and install the latest version of composer. Assuming you're still inside the source directory, run

./build/setup_composer.sh

This should set you up with composer in the root directory of Munkireport. Now we can use composer to pull in all dependencies:

./composer install

If everything went ok, you're set!

Migrate the database

MunkiReport has a SQLite database preconfigured in the settings. To set it up run

php database/migrate.php

For version 5.6.0 and higher, run

./please migrate

Prep .env for no authentication

To run MunkiReport we need to provide at least one authentication method. The easiest is to configure the NOAUTH method which runs MunkiReport without authentication.

echo 'AUTH_METHODS="NOAUTH"' > .env

Development web server

PHP comes with a built in web server that you can use for development purposes. To start it, simply run the following command:

php -S 127.0.0.1:8000 -t public

You should able to visit http://127.0.0.1:8000 and see your MunkiReport dev instance.

Module development

To do work on modules, it is easier to run them next to Munkireport-php. You can set up a modules directory that contains all the modules you want to work on and add the path to this directory to .env. As we already have a volume where munkireport-php resides, we can add the modules directory there.

mkdir /Volumes/Development/modules # Or another place on the filesystem
cd /Volumes/Development/modules
# Clone all modules that are in core
for i in ../munkireport-php/vendor/munkireport/*; do 
 git clone https://github.com/munkireport/$(basename $i); 
done

Now we can add the new module directory to .env

echo "MODULE_SEARCH_PATHS=/Volumes/Development/modules" >> /Volumes/Development/munkireport-php/.env

Composer Settings

Starting with version 3, a composer file was created to manage the dependencies of the project. With 3.3, the modules are now a part of the dependencies which makes managing the composer file more important.

composer.json should now be considered the default values of the project and any alterations should begin to be placed in composer.local.json.

composer.local.json example:

{
    "require": {
        "adldap2/adldap2": "^8.0"
    }
}

To create this file and load into project, simply run the following command:

COMPOSER=composer.local.json composer require adldap2/adldap2:^8.0
composer dumpautoload --no-dev

If you observe a command not found: composer error while attempting to execute COMPOSER commands, the following command will copy the composer binary to /usr/local/bin/:

sudo cp -v composer /Volumes/Macintosh\ HD/usr/local/bin/composer