> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enabling and Octane

> Install a module, turn it on, make changes live and fix what breaks.

![Files, autoloader, enable, migrate, reload, live](https://mintcdn.com/dezerx/dVNBM3sq4VCh7CKa/public/extensions/enabling/top.webp?fit=max\&auto=format\&n=dVNBM3sq4VCh7CKa\&q=85\&s=4b103113708fe02c605a3b6a5977f64d)

## Enable a module

Whether a module is on is stored in the `module_statuses` table. Editing `modules_statuses.json` by hand does nothing.

> [tab] Admin panel
>
> 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.

> [tab] Command line
>
> ```bash theme={null}
> composer dump-autoload
> php artisan module:enable AcmePanelService
> php artisan module:migrate AcmePanelService
> php artisan octane:reload
> ```
>
> Run the reload even if the site seems to catch up on its own. It makes the change certain and immediate.

`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.

> [!WARNING]
>
> 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.

> [accordion] I already broke it
>
> ```bash theme={null}
> composer dump-autoload
> sudo systemctl restart dezerx-octane
> ```
>
> 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.
>
> ```sql theme={null}
> UPDATE module_statuses SET enabled = 0 WHERE name = 'AcmePanelService';
> ```

## 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.

```bash theme={null}
sudo chown -R www-data:www-data Modules/Addons/LoyaltyRewards
composer dump-autoload
```

**3. Rebuild the frontend if it has pages**

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

```bash theme={null}
npm run build
```

**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.

> [!NOTE]
>
> 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.

| You changed | Run |
| - | - |
| PHP in a module, routes or `config/` | `php artisan octane:reload` |
| Code a queued job runs: provisioning, renewals, queued listeners | `php artisan queue:restart` as well |
| Added a class Composer does not know | `composer dump-autoload`, then reload |
| A page in `resources/js` | `npm run build`, no reload |
| Enabled or disabled in the admin panel | Nothing |

```bash Artisan theme={null}
sudo -u www-data php artisan octane:reload
```

```bash systemd theme={null}
sudo systemctl reload dezerx-octane
```

Admin, System also has Reload Octane and Restart All. Run artisan as the site user, usually `www-data`.

> [accordion] Development and PHP-FPM servers
>
> `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

> [accordion] Never exit() or die()
>
> They stop the worker, not just the request. Throw the response instead: `throw new HttpResponseException(redirect('/login'));`

> [accordion] Boot code runs once per worker
>
> `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()`:
>
> ```php theme={null}
> $this->app->make(\Illuminate\Contracts\Http\Kernel::class)
>     ->appendMiddlewareToGroup('web', CaptureReferralFromQuery::class);
> ```

> [accordion] Share Inertia props from middleware
>
> `Inertia::share()` in a provider works for one request and then disappears. Call it from a middleware's `handle()`.

> [accordion] No request state in statics or singletons
>
> They live as long as the worker, so the next customer sees them. Bind per-request services with `scoped()`.

> [accordion] Use RuntimeSnapshot for shared data
>
> ```php theme={null}
> use App\Support\RuntimeSnapshot;
>
> $plans = RuntimeSnapshot::remember('acme:plans', fn () => AcmePlan::all()->toArray());
> ```
>
> 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.

> [accordion] Register listeners once
>
> `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

> [accordion] Symptom and cause
>
> | What you see | Usually |
> | - | - |
> | Change not showing, new route 404 | Octane has not reloaded. Also `queue:restart` for queued code |
> | Copied module missing from Admin, Modules | `composer dump-autoload`, then reload |
> | Every request fails after enabling | Provider not autoloadable. See "I already broke it" |
> | Right once, wrong afterwards | Request state in a static or singleton, or per-request work in `boot()` |
> | Shared Inertia prop vanishes | `Inertia::share()` in a provider. Move it to middleware |
> | Feature does nothing | Wrong class name. Run `module:doctor` |
> | Inertia page not found | `register.ts` key does not match `Inertia::render()`, wrong `../` count, or no `npm run build` |
> | Admin route returns 403 | Permission node has no category, or `routes` include `/admin` |
> | Gateway missing at checkout | `getConfig()['enabled']` is false, or no `flushPaymentGatewayCache()` |
> | Provisioned but nothing exists | A failure was caught and returned. Throw instead |
> | Duplicate emails or log rows | Missing empty `configureEmailVerification()`, or a core listener listed |
> | Cron job stopped | `registerCommandSchedules()` was overridden. Use `moduleSchedule()` |

> [!WARNING]
>
> 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.