Skip to main content
Files, autoloader, enable, migrate, reload, live

Enable a module

Whether a module is on is stored in the module_statuses table. Editing modules_statuses.json by hand does nothing.
Open Admin, Modules and flip the switch. Enabling runs the module’s migrations and clears the permission and gateway caches. Octane picks up the new module list and reloads its workers by itself.
make:module leaves the module disabled and dumps the autoloader for you. --enable also enables and migrates it, after checking that the provider class loads.
Dump the autoloader before you enable, never after. If an enabled module’s provider class is not in the autoloader when a worker boots, every worker fails to boot. Every request then fails, artisan included.
If the classes are really gone, switch the module off in the database and restart again. If you deleted the folder, delete the row too.

Install a module you did not generate

1

Upload the zip

In Admin, Modules choose Upload module and pick a .zip of up to 50 MB. It needs a folder with a module.json in it. The module lands in the right group folder, disabled.
2

Or copy the folder

Put it in the folder that matches its category and make the site user own it.
3

Rebuild the frontend if it has pages

Only when the module ships resources/js/register.ts.
4

Enable it

Flip the switch in Admin, Modules, then run module:doctor.
Updates keep your modules. An update replaces the application, then puts back every module that did not ship in the release, rebuilds the autoloader and rebuilds the frontend.
If a module with the same name ships in a release, the release’s copy wins. Copy a bundled module under a new name instead of patching it. Keep the type suffix (Service, Gateway, Provider) in the name, because the updater uses it to choose the folder.

Make changes live

DezerX runs on Laravel Octane. Each worker boots once and serves thousands of requests, so saved code is not running until the workers reload.
Admin, System also has Reload Octane and Restart All. Run artisan as the site user, usually www-data.
composer dev:octane starts Octane with --watch. It reloads when PHP under Modules/*/*/app or Modules/*/*/routes changes.A server without the PHP extensions RoadRunner needs runs PHP-FPM instead. Reload PHP-FPM there, for example sudo systemctl reload php8.4-fpm. systemctl status dezerx-octane tells you which one you have.

Code that is safe in a worker

They stop the worker, not just the request. Throw the response instead: throw new HttpResponseException(redirect('/login'));
boot(), bootModule(), registerModule() and the top of route files run at worker start. Register routes, listeners and bindings there. Never read the user, request, session or a setting there. Put per-request work in a middleware and append it from bootModule():
Inertia::share() in a provider works for one request and then disappears. Call it from a middleware’s handle().
They live as long as the worker, so the next customer sees them. Bind per-request services with scoped().
It lives in worker memory for at most 60 seconds. Admin saves and Setting writes drop it in every worker. Call RuntimeSnapshot::bump() after a job or webhook changes the data. Store arrays, never model instances or per-user data.
Event::listen() and View::composer() in a controller pile up and slow every later request. Register them in your provider.

When it does not work

Never run php artisan config:cache. Runtime code reads some values with env(), which return null once config is cached. Use php artisan optimize:clear.