|
| 1 | +# AdonisJS Maintenance Mode |
| 2 | + |
| 3 | +>This package enables a simple maintenance mode in AdonisJS applications. When activated, the application temporarily disables access for users, displaying a maintenance message or page. |
| 4 | +
|
| 5 | +## Features |
| 6 | +- Toggle maintenance mode with CLI commands |
| 7 | +- Customize maintenance mode with templates, HTTP status, retries, refresh intervals, redirection, and secret access |
| 8 | +- Exclude specific URLs from maintenance mode |
| 9 | +- Uses `cookie-based` access control |
| 10 | +- File-based, creating a maintenance file in the `tmp/` directory |
| 11 | +## Installation |
| 12 | + |
| 13 | +You can install the package using either node ace or npm. |
| 14 | + |
| 15 | +### Using Adonis CLI |
| 16 | +```bash |
| 17 | + node ace add adonisjs-maintenance-mode |
| 18 | +``` |
| 19 | +### Or Using NPM |
| 20 | +```bash |
| 21 | + npm install adonis-maintenance-mode |
| 22 | +``` |
| 23 | +## Configuration |
| 24 | +After installation, configure maintenance mode in the following ways: |
| 25 | + |
| 26 | +- **Middleware:** A `block_requests_during_maintenance_middleware.ts` file is generated in the middleware folder. Inside this file: |
| 27 | +- Define `excludedUrls:` an array of URLs that should bypass maintenance mode. |
| 28 | + |
| 29 | +Environment Variable: |
| 30 | +- Add `APP_URL` to your .env file to specify your application’s base URL. |
| 31 | + |
| 32 | +## Usage |
| 33 | +Activating Maintenance Mode |
| 34 | + |
| 35 | +Enable maintenance mode via CLI: |
| 36 | + |
| 37 | +```bash |
| 38 | + node ace maintenance:on |
| 39 | +``` |
| 40 | +This command creates a file called `maintenance_mode_on` in the `tmp/` directory, enabling maintenance mode. |
| 41 | + |
| 42 | +Command Options: |
| 43 | +- `--template:` Specify a custom maintenance view template under the resources folder. |
| 44 | +```bash |
| 45 | + node ace maintenance:on --template="pages/errors/503" |
| 46 | +``` |
| 47 | + |
| 48 | +- `--status:` Set a custom HTTP status code (default is 503). |
| 49 | +```bash |
| 50 | + node ace maintenance:on --status=503 |
| 51 | +``` |
| 52 | + |
| 53 | +- `--retry:` Specify a retry interval for retrying requests. |
| 54 | +```bash |
| 55 | + node ace maintenance:on --retry=60 |
| 56 | +``` |
| 57 | + |
| 58 | +- `--refresh:` Set the page refresh interval. |
| 59 | +```bash |
| 60 | + node ace maintenance:on --refresh=30 |
| 61 | +``` |
| 62 | + |
| 63 | +- `--redirect:` Provide a URL to redirect users during maintenance mode. |
| 64 | +```bash |
| 65 | + node ace maintenance:on --redirect=example-url |
| 66 | +``` |
| 67 | + |
| 68 | +- `--secret:` Add a secret key to bypass maintenance mode. When using `--secret`, ensure `APP_URL` is set in your .env file. The default value for `APP_URL` is `http://$HOST:$PORT`, but you may customize it to match your application's URL. |
| 69 | +```bash |
| 70 | + node ace maintenance:on --secret=mysecretkey |
| 71 | +``` |
| 72 | + |
| 73 | +You can also generate a random secret key: |
| 74 | +```bash |
| 75 | + node ace maintenance:on --secret=random |
| 76 | +``` |
| 77 | + |
| 78 | +## Custom Error Pages Configuration |
| 79 | +The `statusPages` configuration in `handler.ts` allows you to define custom renderers for specific HTTP status codes, enabling personalized error pages for various scenarios, including maintenance mode. |
| 80 | + |
| 81 | +```typescript |
| 82 | +protected statusPages: Record<StatusPageRange, StatusPageRenderer> = { |
| 83 | + '503': (error, { view }) => { |
| 84 | + return view.render('pages/errors/503', { error }) |
| 85 | + }, |
| 86 | +} |
| 87 | +``` |
| 88 | +### !! Note on command --template option !! |
| 89 | +If you enable maintenance mode with the `--template` option (e.g., node ace maintenance:on --template=path_to_template), the template specified will automatically be used for the 503 error response, making manual changes in `handler.ts` unnecessary. This provides flexibility for setting custom templates dynamically without requiring code modifications. |
| 90 | + |
| 91 | +## Deactivating Maintenance Mode |
| 92 | +Turn off maintenance mode using the following command: |
| 93 | + |
| 94 | +```bash |
| 95 | +node ace maintenance:off |
| 96 | +``` |
| 97 | + |
| 98 | +This command removes the `maintenance_mode_on` file from the `tmp/` directory. |
| 99 | +## Deactivating Maintenance Mode |
| 100 | +Turn off maintenance mode using the following command: |
| 101 | + |
| 102 | +```bash |
| 103 | +node ace maintenance:off |
| 104 | +``` |
| 105 | +This command removes the `maintenance_mode_on` file from the `tmp/` directory. |
| 106 | + |
| 107 | +## Example Middleware Usage |
| 108 | +In `#middleware/block_requests_during_maintenance_middleware.ts`, you’ll find excludedUrls where you can list URLs that should bypass maintenance mode. This is useful for allowing access to specific resources or pages even during maintenance. |
| 109 | + |
| 110 | +* The `'*'` wildcard allows access to any route that starts with `/users/`, meaning routes like `/users/1`, `/users/profile`, and any other `/users/{sub-route}` will be accessible during maintenance mode. |
| 111 | +* If you add users to the excluded array, all routes beginning with users will be accessible, including `/users` itself. |
| 112 | +* If you specify `users/*`, only routes under `/users/` `(like /users/1, /users/profile)` will be accessible, but not /users itself. |
| 113 | +* Using `users*` allows access to all routes starting with users, equivalent to simply users. |
| 114 | + |
| 115 | +```typescript |
| 116 | +import EnsureMaintenanceMode from 'adonisjs-maintenance-mode14/ensure_maintenance_mode' |
| 117 | + |
| 118 | +/** |
| 119 | + * BlockRequestsDuringMaintenanceMiddleware class extends the functionality of |
| 120 | + * EnsureMaintenanceMode to block requests during maintenance mode, |
| 121 | + * while allowing the specification of certain URLs to be excluded. |
| 122 | + * |
| 123 | + * @class |
| 124 | + * @extends EnsureMaintenanceMode |
| 125 | + * |
| 126 | + * @property {string[]} excludedUrls - An array of URL strings that are excluded from blocking |
| 127 | + * requests during maintenance mode. |
| 128 | + */ |
| 129 | +export default class BlockRequestsDuringMaintenanceMiddleware extends EnsureMaintenanceMode { |
| 130 | + /** |
| 131 | + * An array of URL paths that should be excluded from being blocked during maintenance mode. |
| 132 | + * Requests to these URLs will bypass the maintenance check. |
| 133 | + * |
| 134 | + * @protected |
| 135 | + * @type {string[]} |
| 136 | + */ |
| 137 | + protected excludedUrls: string[] = [ |
| 138 | + 'users/*', |
| 139 | + 'about', |
| 140 | + ] |
| 141 | +} |
| 142 | +``` |
0 commit comments