Overview

Matrix packages offer additional functionality outside the core functionality and feature set. They allow you to add extra features to Matrix when you need them and optionally. You can also add them without requiring to do a full core system upgrade of your Matrix instance.

Packages can add different types of additional functionality to Matrix including:

• New asset types - These are available as regular assets, created within the asset tree.
• New tools - These allow users to perform additional system tasks. Tools are available from the “Tools” drop-down menu in the top toolbar.
• New screens - These add additional screens and functionality to existing asset types.

Some packages may have extra instructions that are supplemental to the common procedures listed in this article.

These instructions for managing packages in your Matrix system are current for version 5.5 of Matrix.

You need server administrator access to your Matrix instance to install and manage Matrix packages.

Installing a package

Matrix packages are provided as a package archive (.tgz).

You install packages by extracting the archive into the /packages directory of your Matrix instance.

Follow these steps to install an extension package on your Matrix instance:

1. Open a terminal and navigate into the target Matrix instance directory. For example:
   • cd /var/www/squiz_matrix
2. Download the package archive to a file system location accessible to your Matrix instance. For example, /path/to/package.tgz.
3. Install the package by extracting the archive into the squiz_matrix/packages directory.
   1. cd /var/www/squiz_matrix/packages
   2. tar -xvf /path/to/package.tgz
4. Navigate into the extracted package’s directory and run each installation step according to the instructions in the package’s README.md file.

Upgrading a package

Before you upgrade any package, you must delete older package versions installed on your Matrix instance.

You should check the Release Notes for the package prior to upgrading to make sure there are no compatibility issues with the Matrix version you are using.

Follow these steps to upgrade a package to a newer version:

1. Verify there are no compatibility issues between the upgrade package and Matrix version you are using.
2. Open a terminal and navigate into the target Matrix instance directory. For example:
   • cd /var/www/squiz_matrix
3. Delete any previous installation of the package. For example:
   • rm -rf packages/json_web_token
4. Download the updated package archive to a file system location accessible to your Matrix instance. For example, /path/to/package.tgz.
5. Install the package by extracting the archive into your squiz_matrix/packages directory.
   1. cd /var/www/squiz_matrix/packages
   2. tar -xvf /path/to/package.tgz
6. Navigate into the extracted package’s directory and run each installation step according to the instructions in the package's README.md file.

Uninstalling a package

A system administrator can uninstall a package only if the package's documentation contains instructions on how to safely remove the package from Matrix.

If a package does not provide uninstallation instructions, do not attempt to uninstall the package yourself.
Contact your account manager to request assistance with deleting the package safely.

Follow these supplemental uninstallation steps after reading the package's uninstallation documentation:

1. Ensure you have completed any initial uninstallation steps described in the package’s documentation.
2. Once all prerequisites are met, open a terminal and navigate into the target Matrix instance directory. For example:
   • cd /var/www/squiz_matrix/
3. Remove the package directory from the Matrix instance. For example:
   • rm -rf packages/json_web_token
4. Run Step 2 and Step 3 scripts to finalise the package removal process.
   1. sudo -u apache php install/step_02.php $PWD
   2. sudo -u apache php install/step_03.php $PWD