General Upgrade Procedures

• Maintenance Mode
  • Down
  • Up
• Back Up Database and Settings
  • SQLite
  • MySQL
  • Backup Your Settings
• Upgrade
  • Use git
    • Composer Update
  • Download Zip Archive
• Run migrations
• Maintenance Mode Up
• Clear your cache and HTML5 local storage
• Create Client Installer Package

If you are upgrading MunkiReport from older versions (2.x, 3.x), before performing the upgrade, please read through How to Upgrade Versions, so that you are aware of the configuration changes that need to happen with each version.

Maintenance Mode

If you need to do some work on the MunkiReport application, e.g. do some database migrations, it is often advised to put the application into maintenance mode. When in this mode, MunkiReport does not accept client requests anymore and most web views will show that the application is not available.

Down

To put MunkiReport 5.6.1 or higher into maintenance mode you may use:

./please down

Or, to put MunkiReport into maintenance mode, simply create a file called down into the storage/framework directory. On the command line:

touch /path/to/munkireport/storage/framework/down

Up

After maintenance is done, bring MunkiReport 5.6.1 or higher out of maintenance mode you may use:

./please up

Or, remove the file and MunkiReport will operate as normal again. On the command line:

rm /path/to/munkireport/storage/framework/down

In the future you will be able to do this with a command line tool.

Back Up Database and Settings

Although we try to make upgrading as smooth as possible, there may be cases where the upgrade does bad things to your database. Use a backup strategy that fits the database back end you are using.

SQLite

The standard location of the SQLite database is in the app/db directory, if you're upgrading by downloading the new version of Munkireport and copying the files over the previous version, this database is going to be lost. To backup your SQLite database safely, navigate to the directory in which your database is located and run:

sqlite3 db.sqlite '.backup db.backup.sqlite'

Now move db.backup.sqlite out of the way for safe keeping.

MySQL

You can backup a MySQL database using different methods:

• via the command line using mysqldump

mysqldump -u root -p --databases munkireport > /tmp/munkireport_20181216.bak

• with phpMyAdmin if you have that installed
• with a fat client like Sequel Pro

If your database does get deleted, you can also just wait until your clients fill it up again

Backup Your Settings

MunkiReport has moved away from config.php, but if you're running a very old version, you might still have it. Put that somewhere safe for now.

Make a copy of .env and composer.local.json and store them in a safe place.

cp {.env,composer.local.json} /tmp

Note: if you have a local user you will have to back that yml file as well from the local/users folder.

Upgrade

Use git

The easiest and safest way to upgrade is using git. When you use git, the SQLite database does not get overwritten and your .env and composer.local.json files stay intact. With git it is easy to revert the update if things don't work out so well. The following assumes that you set up munkireport with git

To checkout the latest master:

git checkout main
git pull

Composer Update

Starting with version 3, after an upgrade, the dependencies must be updated by running the following command:

composer update --no-dev

Download Zip Archive

If you can't use git, then you can copy the new files to the proper location. If you're running MunkiReport from a subdirectory called 'munkireport', you can rename that directory to 'munkireport.old'. Then you put the new version up under 'munkireport' and copy your database and settings files to 'munkireport'. See also Download Zip Archive

touch /path/to/munkireport/storage/framework/down

Run migrations

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 the Update button.

Maintenance Mode Up

If you have put your site in maintenance mode, you must turn it off.

rm /path/to/munkireport/storage/framework/down

Clear your cache and HTML5 local storage

After a successful upgrade, you might find that pages don't load properly. This is common, and is usually related to your browser caching the GUI elements from the old version.

To confirm this is the case, try loading your site from another web browser. If that loads fine, clear your primary browser's cache and HTML5 local storage.

For Safari:

1. Hold Command and Option, then press C.
2. Enter the following code into the window that pops up: localStorage.clear()
3. Press Enter to submit.
4. In the Safari menu, select Clear History.

Another option is to hold ⇧ (Shift) and click reload.

Create Client Installer Package

A new client installer is only needed if one of two things are true:

1. A new module is enabled/installed by the admin.
2. A module that is in use has its install script changed. The install script is the script that runs on the client that pulls the information together to send to the server. Many times a module is updated while the install script does not change. Check the release notes for whether a module gets updated.

Once you update the server, and one of the above things are true, the clients will need a new update package as well. Make sure to enable any new modules that you want to include before doing this step. Instructions are available on the Client Setup wiki page.