Skip to main content

Module Installation

How to install, uninstall, and manage modules on the ION Guard platform in a production environment.

Overview​

Modules are distributed as encrypted packages (.enc) that contain the source code, migrations, compiled frontend, and settings. Installation is done through the web interface or via the command line.

Installation via the web interface​

Required profile

Requires Platform Admin.

  1. Go to Modules (/modules) in the sidebar
  2. Click "Install Module"
  3. Select the module's .enc file (maximum 100 MB)
  4. Wait for processing

What happens internally​

  1. Decryption — The .enc package is unpacked with the module release key (MODULE_RELEASE_KEY), via ModuleReleaseEncryption. This key is fixed and shared across installations (it only serves to wrap/unwrap the distribution file). Do not confuse it with the MODULE_ENCRYPTION_KEY, which is generated per installation and encrypts sensitive runtime data (gateway credentials, tokens in the database)
  2. Validation — Checks the ZIP structure: it requires {Module}/{Module}ServiceProvider.php, all files under the {Module}/ directory, and no path traversal (.. or an absolute path)
  3. Staging — Extracts to a temporary directory with a random name (.{module}.staging-{rand}) on the same filesystem as the destination, so the swap is atomic
  4. Atomic swap — Renames the existing module to .bak-{timestamp} (if any) and moves the staging to its final position in app/Modules/
  5. Migrations — Runs php artisan migrate --force and re-optimizes the cache (optimize + opcache_reset)
  6. Assets — Publishes the frontend assets
  7. Docker Compose — Regenerates modules_runtime.yml with the workers declared by the new module
  8. Restart — Schedules the PHP-FPM restart (via inotify watcher, without access to the Docker socket) to register the ServiceProvider

Installation and uninstallation are recorded in the audit trail (module_installed / module_uninstalled).

In case of failure​

If any step fails after extraction:

  • The staging directory is removed
  • The backup of the previous version (if it existed) is restored
  • Assets are unpublished
  • An error message is displayed in the interface
Migrations are not reverted automatically

If the failure occurs after the migrations, they are not reverted automatically. You will need to run a manual rollback if necessary:

./scripts/comp.sh exec -T ionguard_php php artisan migrate:rollback

Module update​

To update an already installed module, simply install the new version over the existing one. The system:

  1. Backs up the current version
  2. Installs the new version
  3. Runs the new migrations
  4. Keeps the previous version as a backup until success is confirmed

Uninstallation​

Prerequisites​

Before uninstalling, resolve all of the module's active alerts. Uninstallation is blocked if there are unresolved alerts.

Via the interface​

  1. On the module card in Modules (/modules), click "Uninstall"
  2. Confirm in the dialog

What is removed​

  • Per-site enablement records (site_modules)
  • Module files in app/Modules/
  • Published assets
  • Workers in Docker Compose

What is preserved​

  • Database tables — Data created by the module remains
  • Audit records — Log of the module's actions
  • Backups — Existing backups are not affected

Installation logs​

All module operations are recorded in a dedicated log:

storage/logs/modules.log

Each operation includes a request_id for traceability. The log is rotated daily with a default retention of 14 days.

Post-installation verification​

After installing a module:

# Check whether the module is registered
./scripts/comp.sh exec -T ionguard_php php artisan tinker --execute="
    app(\App\Modules\ModuleRegistry::class)->all()
"

# Check whether workers were created (if the module declares workers)
./scripts/comp.sh ps

# Health check
./scripts/healthcheck.sh

Per-site enablement​

After installation, the module must be enabled for each site where it will be used. See Modules — User Guide for instructions.