• Stars
    star
    476
  • Rank 92,280 (Top 2 %)
  • Language
    Dockerfile
  • License
    MIT License
  • Created over 8 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🐳 Official Docker Image for PM2 runtime

PM2

Production ready nodeJS Docker image including the PM2 runtime.

The goal of this image is to wrap your applications into a proper Node.js production environment. It solves major issues when running Node.js applications inside a container like:

  • Correct PID 1 signals Handling & Forwarding
  • Graceful application Start and Shutdown
  • Seamless application clustering to increase performance and reliability

Further than that, using PM2 as a layer between the container and the application brings PM2 features like application declaration file, customizable log system, source map support and other great features to manage your Node.js application in production environment.

Tags available

Image Name Operating system Dockerfile
keymetrics/pm2:latest-alpine Alpine latest-alpine
keymetrics/pm2:18-alpine Alpine 15-alpine
keymetrics/pm2:16-alpine Alpine 15-alpine
keymetrics/pm2:15-alpine Alpine 15-alpine
keymetrics/pm2:14-alpine Alpine 14-alpine
keymetrics/pm2:12-alpine Alpine 12-alpine
keymetrics/pm2:10-alpine Alpine 10-alpine
Image Name Operating system Dockerfile
keymetrics/pm2:latest-buster Debian Buster latest-buster
keymetrics/pm2:18-buster Debian Buster 18-buster
keymetrics/pm2:16-buster Debian Buster 16-buster
keymetrics/pm2:15-buster Debian Buster 15-buster
keymetrics/pm2:14-buster Debian Buster 14-buster
keymetrics/pm2:12-buster Debian Buster 12-buster
keymetrics/pm2:10-buster Debian Buster 10-buster
Image Name Operating system Dockerfile
keymetrics/pm2:latest-stretch Debian Stretch latest-stretch
keymetrics/pm2:18-stretch Debian Stretch 18-stretch
keymetrics/pm2:16-stretch Debian Stretch 16-stretch
keymetrics/pm2:15-stretch Debian Stretch 15-stretch
keymetrics/pm2:14-stretch Debian Stretch 14-stretch
keymetrics/pm2:12-stretch Debian Stretch 12-stretch
keymetrics/pm2:10-stretch Debian Stretch 10-stretch
Image Name Operating system Dockerfile
keymetrics/pm2:latest-jessie Debian Jessie latest-jessie
keymetrics/pm2:18-jessie Debian Jessie 18-jessie
keymetrics/pm2:16-jessie Debian Jessie 16-jessie
keymetrics/pm2:15-jessie Debian Jessie 15-jessie
keymetrics/pm2:14-jessie Debian Jessie 14-jessie
keymetrics/pm2:12-jessie Debian Jessie 12-jessie
keymetrics/pm2:10-jessie Debian Jessie 10-jessie
Image Name Operating system Dockerfile
keymetrics/pm2:latest-slim Debian Stretch (minimal packages) latest-slim
keymetrics/pm2:18-slim Debian Stretch (minimal packages) 18-slim
keymetrics/pm2:16-slim Debian Stretch (minimal packages) 16-slim
keymetrics/pm2:15-slim Debian Stretch (minimal packages) 15-slim
keymetrics/pm2:14-slim Debian Stretch (minimal packages) 14-slim
keymetrics/pm2:12-slim Debian Stretch (minimal packages) 12-slim
keymetrics/pm2:10-slim Debian Stretch (minimal packages) 10-slim

You can find more information about the image variants here.

The build process of these images is automatically triggered each time NodeJS's Docker images are built. The build process of these images is automatically triggered each time Docker PM2's GitHub repo master branch is pushed. The build process of these images is automatically triggered each time PM2's GitHub repo master branch is pushed.

Usage

Let's assume the following folder structure for your project.

`-- your-app-name/
    |-- src/
        `-- app.js
    |-- package.json
    |-- pm2.json     (we will create this in the following steps)
    `-- Dockerfile   (we will create this in the following steps)

Create a pm2 ecosystem file

Create a new file called pm2.json with the following content:

{
  "name": "your-app-name",
  "script": "src/app.js",
  "instances": "2",
  "env": {
    "NODE_ENV": "development"
  },
  "env_production" : {
    "NODE_ENV": "production"
  }
}

You can choose the name of the ecosystem file arbitrarily, but we will assume you called it pm2.json in the following steps.

See the documentation for more information about how to configure the ecosystem file.

Create a Dockerfile file

Create a new file called Dockerfile with the following content:

FROM keymetrics/pm2:latest-alpine

# Bundle APP files
COPY src src/
COPY package.json .
COPY pm2.json .

# Install app dependencies
ENV NPM_CONFIG_LOGLEVEL warn
RUN npm install --production

# Show current folder structure in logs
RUN ls -al -R

CMD [ "pm2-runtime", "start", "pm2.json" ]

See the documentation for more info about the pm2-runtime command.
All options available are listed here.

Build and Run your image

From your Node.js app project folder launch those commands:

$ docker build -t your-app-name .
$ docker run your-app-name

Custom configurations

Enable git auto-pull

If you want to Automatically synchronize your application with git add this into your Dockerfile:

RUN pm2 install pm2-auto-pull

Make sure the .git is present in your application source folder.

Enable Monitor server

If you want to Automatically monitor vital signs of your server add this into your Dockerfile:

RUN pm2 install pm2-server-monit

Use Keymetrics.io dashboard

Keymetrics.io is a monitoring service built on top of PM2 that allows to monitor and manage applications easily (logs, restart, exceptions monitoring, etc...). Once you created a Bucket on Keymetrics you will get a public and a secret key.

To enable Keymetrics monitoring with pm2-runtime, you can whether use the CLI option –public XXXX and –secret YYYY or you can pass the environment variables KEYMETRICS_PUBLIC and KEYMETRICS_SECRET.

From your Node.js app project folder launch those commands:

$ docker build -t your-app-name .
$ docker run -e KEYMETRICS_PUBLIC=XXXX -e KEYMETRICS_SECRET=YYYY your-app-name

Make sure that the ports 80 (TCP outbound), 443 (HTTPS outbound) and 43554 (TCP outbound) are allowed on your firewall.

See the troubleshooting in case you encounter any problem.

Enabling Graceful Shutdown

When the Container receives a shutdown signal, PM2 forwards this signal to your application allowing to close all the database connections, wait that all queries have been processed or that any other final processing has been completed before a successful graceful shutdown.

Catching a shutdown signal is straightforward. You need to add a listener in your Node.js applications and execute anything needed before stopping the app:

process.on('SIGINT', function() {
  db.stop(function(err) {
    process.exit(err ? 1 : 0);
  });
});

By default PM2 will wait 1600ms before sending a final SIGKILL signal. You can modify this delay by setting the kill_timeout option inside your application configuration file.

Expose health endpoint

The --web [port] option allows to expose all vital signs (docker instance + application) via a JSON API.

CMD ["pm2-runtime", "start", "pm2.json", "--web"]

or

CMD ["pm2-runtime", "start", "pm2.json", "--web", "port"]

Useful commands

Command Description
$ docker exec -it <container-id> pm2 monit Monitoring CPU/Usage of each process
$ docker exec -it <container-id> pm2 list Listing managed processes
$ docker exec -it <container-id> pm2 show Get more information about a process
$ docker exec -it <container-id> pm2 reload all 0sec downtime reload all applications

Documentation

The documentation can be found here.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

License information for the software contained in this image can be found here (pm2) and here (node).

More Repositories

1

pm2-logrotate

Automatically rotate all applications logs managed by PM2
JavaScript
1,243
star
2

pmx

(DEPRECATED) use @pm2/io instead (drop-in replacement) https://github.com/keymetrics/pm2-io-apm
JavaScript
265
star
3

pm2-server-monit

Monitor server CPU / Memory / Process / Zombie Process / Disk size / Security Packages / Network Input / Network Output
JavaScript
261
star
4

pm2-io-apm

PM2.io APM for Node.JS
TypeScript
147
star
5

pm2-auto-pull

This app will automatically pull all applications managed by PM2 to the latest version (compatible git)
JavaScript
136
star
6

vizion

Git/Subversion/Mercurial repository metadata parser
JavaScript
39
star
7

cli-tableau

Pretty unicode tables for the CLI with Node.JS
JavaScript
31
star
8

doc-pm2

DEPRECATED
CSS
28
star
9

pm2-io-js-api

PM2.io API Client for Javascript
JavaScript
28
star
10

pm2-plus-tech-questions

http://docs.keymetrics.io/docs/pages/faq-troubleshooting/
27
star
11

pm2-redis

Module to monitor redis
JavaScript
23
star
12

event-loop-inspector

(DEPRECATED) Dump event loop's current stats.
JavaScript
21
star
13

pm2-ebs-demo

Demo for PM2/Keymetrics integration for AWS with simple express server
JavaScript
17
star
14

app-playground

Code level metrics with Keymetrics
JavaScript
17
star
15

pm2-io-apm-go

Golang APM for PM2 Enterprise
Go
16
star
16

on-premise

Documentation for the on-premise version of PM2 Enterprise
Mustache
13
star
17

pm2-logs

Pm2 cli logs interface
JavaScript
12
star
18

pm2-elasticsearch

PM2.io Module to monitor Elasticsearch nodes
JavaScript
12
star
19

node-runtime-stats

A module that forwards stats from NodeJS runtime
C++
9
star
20

pm2-io-agent

PM2.io NodeJS Agent embed inside PM2
JavaScript
8
star
21

pm2-io-agent-node

PM2.io Agent Standalone for NodeJS
JavaScript
8
star
22

keymetrics.github.io

Keymetrics documentation website
CSS
7
star
23

interdb

👷 Local and shared database
JavaScript
6
star
24

synergy-office-control-iot

How we control our whole Paris Office with our solutions
JavaScript
5
star
25

pm2-cluster-benchmark

Benchmarking PM2 cluster vs Raw Node vs Nginx vs Haproxy
Nginx
5
star
26

keymetrics-widget

JavaScript
5
star
27

nginx-interface

Module to interface NGINX with PM2
C
5
star
28

fullstack-workshop

FullStack London 2015 - PM2 & Keymetrics workshop
JavaScript
4
star
29

install

Script to install NVM + Node + pm2 (script install.sh on app.keymetrics.io)
Shell
3
star
30

pm2-workshop

Pm2 Workshop repository
JavaScript
3
star
31

docker-interface

Node.js interface wrapper around key commands of docker and docker-compose
2
star
32

pm2-masterclass

JavaScript
2
star
33

deep-metrics

Retrieve metrics about popular modules automatically
JavaScript
2
star
34

pm2-io

SCSS
2
star
35

k8s-ansible

Ansible tasks to provision a K8S cluster
2
star
36

pm2-generate-metrics

Generate multiple graphs
JavaScript
2
star
37

branding

Keymetrics/PM2 Branding
2
star
38

pm2-io-apm-python

Python Integration for PM2.io
Python
2
star
39

trassingue

(DEPRECATED)
JavaScript
2
star
40

sample-apps

Tracing
JavaScript
1
star
41

origa

JavaScript
1
star
42

envision-sdk

🏗️ SDK to build module for Envision
JavaScript
1
star
43

envision-video

📹 Upload video for infinite replay
JavaScript
1
star
44

km_universe

JavaScript
1
star
45

pm2-tar-auto-update

JavaScript
1
star
46

tracing

1
star
47

app-showcase

JavaScript
1
star
48

simplicity

R&D blinkstick
JavaScript
1
star
49

interdb-hub

JavaScript
1
star
50

pm2-digital-signage

JavaScript
1
star
51

cpu-search

Retrieve CPU model from CPU benchmark CSV
TypeScript
1
star
52

extrareqp2

JavaScript
1
star
53

app-playground-tracing

An example app to send traces to pm2 enterprise
JavaScript
1
star
54

wakanda-hydroplant

JavaScript
1
star
55

xeon

HTML
1
star