-
Notifications
You must be signed in to change notification settings - Fork 138
How to Upgrade Versions
This guide is meant to inform you of the changes that have occurred for each major version change. If you are upgrading from 2.x or 3.x, it is best to read through this document so that you are aware of what configuration settings will need to be updated. For instructions on performing the upgrade, please see the General Upgrade Procedures.
Mac Admins Python version 3.10 is required to be installed on each client computer.
Version 3.10 of Mac Admins Python can be found on this page: https://github.com/macadmins/python/releases/tag/v3.10.11.80742
Minimum version of PHP is now 8
MunkiReport Python2 is required to be installed on each client computer.
The latest release of MunkiReport Python2 can be found on this page: https://github.com/munkireport/MunkiReport-Python/releases
Minimum version of PHP is now 7.3
The database/migrate.php
command has been replaced in favor of ./please migrate
Minimum version of PHP is now 7.2.5
The localadmin
module is retired in favour of the more versatile users
module. If you have localadmin
enabled in .env
, please replace with users
.
This release changes the way MunkiReport runs on the client. MunkiReport now has it's own launchDaemon, which means that it will no longer take up time when munki runs it's pre- and postflight scripts.
The MunkiReport scripts have moved to /usr/local/munkireport
MunkiReport log files are now found in /Library/MunkiReport/Logs/
To take advantage of the new scripts, create a new client package and distribute to your munki clients.
MunkiReport does not run scripts in /usr/local/munki/preflight.d
, /usr/local/munki/postlight.d
and /usr/local/munki/preflight_abort.d
anymore! If you depended on these locations, please consider creating your own implementation for these. Also note that MunkiReport will not clean up the legacy directories.
This release changes the entire configuration system to .env
. This means that config.php
and config_default.php
are no longer in use. To aid in moving the old configuration to the new one, a migration script is available. To run the migration script use the terminal:
cd /path/to/munkireport
./build/config_to_env
There is a new directory called local
that is used for user accounts, dashboards, certificates and module specific yaml files. The migration script will use those directories to store some of the converted items (users, certs, dashboard layouts).
You can override the local
directory location by setting
LOCAL_DIRECTORY_PATH="/path/to/local/directory/"
in your .env
file. This allows you to keep your local configs separate from the MunkiReport files and optionally store them in your own versioning system.
MunkiReport version 3.3 brings some major changes to module configuration.
Notable changes:
- Add module search path
- Modules are split off into separate repos
- Added composer-merge plugin (allows for local
composer.json
file)
If you have copied config_default.php previously, ensure that you at least update your config.php first line from:
<?php if ( ! defined( 'KISS' ) ) exit; to <?php
remove the line: $conf['module_path'] = APP_ROOT . "/vendor/munkireport/";
It has been common practice to copy config_default.php
to config.php
and to edit those things that need changed. This is no longer the case and can cause unintended consequences because of the changes to the way MunkiReport manages settings. Clear out any old default settings from config.php.
While the upgrade procedure for 3.3 remains the same, the location of all modules has moved from app/modules
to vendor/munkireport
. This directory is updated when the composer.json
or composer.local.json
files are updated and composer update
is run.
Custom module location has also changed. There is no longer a custom
folder by default and a module search path can be configured in the .env
file to facilitate custom modules. Example:
MODULE_SEARCH_PATHS=/full/path/to/munkireport/custom-modules
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
.
{
"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
A module creator can now create modules in a dedicated repo. To make them available with composer a packagist account must be created and linked to their GitHub account. Once linked, creating releases in the module will automatically create a package that can be installed in composer.local.json
.
Example: https://packagist.org/packages/joncrain/manifests
COMPOSER=composer.local.json composer require joncrain/manifests:^1.0
composer dumpautoload --no-dev
MunkiReport version 3 attempts to solve a couple of longstanding issues concerning security, dependency management and database management. We're moving slowly to using eloquent as replacement for the KISS database abstraction. A ton of work has been done by @mosen to make this all work.
Most notable changes are:
- Minimum PHP version is 7.0.27
- Document root is now in a directory called
/public
. The best practice is to serve your munkireport instance from this directory or make a symlink to this directory. - If you install MunkiReport via git pull, you need to install all dependencies first via
composer
- There is a new database configuration format
$conf['connection']
. See config_default.php on how to use it. - Database migrations (also the initial ones) are not running automatically. You need to run migrations via the command line tool
php database/migrate.php
To take advantage of these security changes see the following common scenarios when updating:
An In-Place upgrade will allow you to keep the existing URL structure you have today but incorporate the security changes. There is no need to adjust apache config changes with this method. Note: this method relies on .htaccess
URL rewrites provided in the updated code to redirect traffic accordingly.
After following the instructions on General Upgrade Procedures to update the code, you can do the following:
- Move the existing MunkiReport folder to a directory outside of the hosted webroot.
mv /var/www/webroot/munkireport-php /Volumes/SecureConnectedStorage/munkireport-php
- Create a symlink of the munkireport-php public folder from the new location to the webroot location. Name the link the same as the folder name of munkireport-php when it was in the webroot.
ln -s /Volumes/SecureConnectedStorage/munkireport-php/public /var/www/webroot/munkireport-php
MunkiReport version 3 uses a dependency manager called composer
. Make sure you have composer installed in the munkireport-php directory before you proceed. Instructions on how to install composer can be found on the Composer Website. After you have installed composer on your system, run the following from the munkireport-php directory:
php composer install --no-dev --no-suggest --optimize-autoloader
This will download and install all the dependencies for MunkiReport in a vendor
directory in munkireport-php and generate the autoload files.
MunkiReport V3 switches to the eloquent database framework. This framework needs a different db configuration than the previous PDO config. See config_default.php
for examples like below:
SQLite is configured by default. You can override the path to the database file:
$conf['connection'] = [
'driver' => 'sqlite',
'database' => 'path/to/db.sqlite',
];
$conf['connection'] = [
'driver' => 'mysql',
'host' => 'your.mysql.hostname',
'port' => 3306,
'database' => 'munkireport',
'username' => 'munkireport_user',
'password' => 'munkireport_pass',
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'strict' => true,
'engine' => 'InnoDB',
];
The database migration method has changed in version 3. Previously, database changes would happen automatically when a client would upload new data or when accessing a view that needed changes in the web interface. That is no longer the case.
The config.php value to allow migrations ($conf['allow_migrations'] = TRUE;
) is no longer respected and can be removed as of v3.
The admin must manually trigger a database migration. That can be done two ways:
- Run the migration script from the munkireport-php folder on the server via CLI
./please migrate
- In the web console access the
Admin->Database
menu and click theUpdate
button.
If you have custom CSS or Javascript overrides in use there may be some configuration changes to make in config.php and the file structure. There are two options:
- Place your custom files in a web accessible location, outside of the munkireport-php folder structure and change your configuration settings to access it directly:
$conf['custom_css'] = 'https://server.com/some/accessible/url/custom.css';
$conf['custom_js'] = 'https://server.com/some/accessible/url/custom.js';
- Store the custom files in their current location or somewhere accessible the server and add a symlink to the files in the
public
folder. For this example say your custom files are stored in the directorymunkireport-php/custom/
cd munkireport-php/public
ln -s ../custom/custom.css custom.css
ln -s ../custom/custom.js custom.js
The config.php
setting in this instance would be the following since the symlinks are in the root of the public folder:
$conf['custom_css'] = '/custom.css';
$conf['custom_js'] = '/custom.js';
When updating from v2.x, there is a change of the ARD table column names. The migration currently does not seem to fix the issue. The old column names are "Text1" (through h4) and the new column names are "text1". We have seen issues with the newer MunkiReport versions not pulling in these columns correctly.
- General Upgrade Procedures
- How to Upgrade Versions
- Troubleshooting Upgrades
- Migrating sqlite to MySQL