https://github.com/aymenjd/pm2-restart-hook
A PM2 module to automatically restart child processes when a parent app is restarted
https://github.com/aymenjd/pm2-restart-hook
manager npm pm2 pm2-module
Last synced: 5 months ago
JSON representation
A PM2 module to automatically restart child processes when a parent app is restarted
- Host: GitHub
- URL: https://github.com/aymenjd/pm2-restart-hook
- Owner: AYMENJD
- License: mit
- Created: 2025-09-15T03:07:47.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-21T08:01:52.000Z (9 months ago)
- Last Synced: 2025-10-30T22:47:49.338Z (7 months ago)
- Topics: manager, npm, pm2, pm2-module
- Language: JavaScript
- Homepage:
- Size: 32.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pm2-restart-hook [](https://www.npmjs.com/package/pm2-restart-hook) [](LICENSE)
A simple and lightweight PM2 module that creates a parent-child dependency between your applications, automatically restarting child processes when their designated parent application is restarted
### Features
`pm2-restart-hook` offers several key features for better process management:
- **Dependency Management**: Easily create a parent-child relationship between any PM2-managed applications
- **Automated Cascading Restarts**: When a parent app restarts, all its children are automatically restarted
- **Highly Configurable**: Customize behavior using environment variables, with sensible defaults for zero-configuration use
- **Lightweight & Simple**: No external dependencies beyond PM2 itself
### Requirements
- PM2 v5.0.0+
### Installation
You can install the module directly from NPM:
```bash
pm2 install pm2-restart-hook
```
### How It Works
The hook identifies the parent-child relationship using a simple environment variable. When a parent application restarts, the hook finds all other applications that have their `PM2_PARENT_APP` environment variable set to the parent's name and restarts them
### Usage Example
The best way to manage parent-child applications is with an `ecosystem.config.js` file
1. **Create your applications.** For this example, we'll use a placeholder script `dummy-app.js`
2. **Define the relationship in `ecosystem.config.js`:**
```js
// ecosystem.config.js
module.exports = {
apps: [
// 1. The Parent Application
{
name: 'api-server',
script: 'api.js',
// Common reasons for automated restarts
max_memory_restart: '500M',
cron_restart: '0 2 * * *', // Restart every day at 2 AM
},
// 2. Child Worker #1
{
name: 'email-worker',
script: 'worker.js',
env: {
// This links the worker to its parent.
// The value MUST match the parent's 'name'.
PM2_PARENT_APP: 'api-server',
},
},
// 3. Child Worker #2
{
name: 'analytics-worker',
script: 'worker.js',
env: {
PM2_PARENT_APP: 'api-server',
},
},
],
};
```
3. **Start your applications:**
```bash
pm2 start ecosystem.config.js
```
Now, whenever `api-server` restarts (whether from its cron schedule, memory limit, or a manual command), `email-worker` and `analytics-worker` will be gracefully restarted one after another
### Configuration
You can configure the hook's behavior by setting variables on the module itself using the `pm2 set` command
| Environment Variable | Description | Default |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------ |
| `PARENT_ENV_KEY` | The environment variable key used to identify the parent app | `PM2_PARENT_APP` |
| `IGNORE_MANUAL_RESTARTS` | If set to `true`, manual restarts (`pm2 restart `) will be ignored | `true` |
| `CHILD_RESTART_DELAY_MS` | The delay in milliseconds between restarting each child process to prevent system overload | `200` |
**Example of setting a configuration variable:**
```bash
# Make the hook to not ignore manual restarts
pm2 set pm2-restart-hook:IGNORE_MANUAL_RESTARTS false
# Change the restart delay to 1 second
pm2 set pm2-restart-hook:CHILD_RESTART_DELAY_MS 1000
```
### Thanks To
- You for viewing or using this project
- The Keymetrics team for creating and maintaining the powerful PM2 process manager
### License
This project is licensed under the MIT [License](LICENSE).