Nomenclature Predictably Misunderstood

    @elife/pm2

    3.6.1 • Public • Published

    PM2 for Electron

    Process Manager

    PM2 is a project that is stable, robust, and well designed. However, when running for Electron, it has two issues:

    1. Electron has an internal filesystem format called ASAR which improves the performance of Electron apps. PM2 is unable to work with this format.
    2. Electron distributes it's own (embedded) NodeJS. However, PM2 ignores this and requires the end user to install another version of NodeJS.

    Hence I created this new "Process Manager". It can be used without Electron of course but will also work perfectly with Electron without any of the existing PM2 issues.

    Features

    1. Start multiple processes
    2. Start Python and NodeJS processes
    3. Understands NodeJS modules (you can just point to the module folder)
    4. WORKS WITH EMBEDDED Electron NodeJS
    5. Stop any started process whenever you want
    6. Direct the output to a log file
    7. Set the working directory and environment if needed
    8. Pass any required arguments to the scripts
    9. KEEP-ALIVE: Automatically restarts the process if crashes (completely configurable)

    Usage

    Getting started

    const pm2 = require('@tpp/pm2')
    
    pm2.start({
        script: 'path/to/script.py',
    })

    Checking for errors with a callback

    pm2 functions take an optional callback that is invoked when there are errors.

    pm2.start({
        script: 'path/to/script.py',
    }, (err, pid) => {
        ...
    })

    The start callback can be invoked multiple times - for each error in the process and when the process restarts. The callback also contains the PID of the process when it starts. A callback without pid or err means it has terminated cleanly.

    Passing arguments to scripts

    pm2.start({
        script: 'path/to/script.py',
        args: ['say','hello'],
    })

    Setting Current Working Directory

    pm2.start({
        script: 'script.py',
        cwd: '/path/to/folder',
    })

    Using Node modules

    Because pm2 understands Node modules we can simply point to the module folder and it will pick up the correct starting point.

    pm2.start({
        cwd: '/path/to/npm/module/',
    })

    Direct output to log file

    pm2.start({
        cwd: '/path/to/npm/module/',
        log: 'mylog.log',
    })

    Stopping a process

    In order to stop a process it needs to be given a name:

    pm2.start({
        name: 'my-process',
        cwd: '/path/to/npm/module/',
    })
    
    pm2.stop('my-process')

    stop also takes an optional callback that will be called when stopped/error.

    pm2.stop('my-process', (err) => {
        ...
    })

    Stopping all processes

    You can stop all running processes (named or un-named).

    pm2.stopAll()

    Restart a process

    You can also restart a named process.

    pm2.restart('my-process')

    Note that restart does not take a callback. It uses the same callback you provided to start.

    Setting the environment

    You can set the environment of the running process:

    pm2.start({
        script: 'path/to/script.py',
        env: ENVIRONMENT_OBJECT,
    })

    Stopping Hook

    If you want to clean up your sub-processes or simply stop cleanly in a sub-process you can use the onstopping event handler:

    const pm2 = require('@tpp/pm2')
    pm2.onstopping(() => {
        ...
    })

    Of course this only works if you're sub-process is a NodeJS module.

    Crashing & Restarts

    Crash

    By default pm2 will restart any crashed processes. To prevent 'spinning' it will restart each time with a delay:

    • First crash? Wait 100ms before restarting
    • Crashed again? Wait 500ms before restarting
    • Crashed again? Wait 1 second, then 10 seconds, then 30 seconds, then 1 minute, then 5 minutes before restarting
    • Still crashing? Re-try every 15 minutes

    If it has been running successfully for 30 minutes assume started ok.

    This is all configurable using the restartAt and restartOk parameters. The default parameters for the behaviour given above is:

    pm2.start({
        cwd: '/path/to/npm/module/',
        restartAt: [100, 500, 1*1000, 10*1000, 30*1000, 60*1000, 5*60*1000],
        restartOk: 30 * 60 * 1000,
    })

    You can design any restart strategy you want using the above parameters.

    No Restart

    You can turn the restarting behaviour off completely by setting restartAt to [] or [0].

    Terminal Output coloring

    In some cases the output of programs designed for the terminal can contain ANSI Escape Codes. To remove them specify stripANSI:true as an option.

    pm2.start({
        cwd: '/path/to/npm/module/',
        log: 'mylog.log',
        stripANSI: true,
    })

    This is usually because you want a clean log file.

    TODO

    [ ] Add Support for more process types (besides just python and node)

    Install

    npm i @elife/pm2

    DownloadsWeekly Downloads

    36

    Version

    3.6.1

    License

    ISC

    Unpacked Size

    677 kB

    Total Files

    28

    Last publish

    Collaborators

    • charleslobo