Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/andruschka/pm2-meteor

Simplest way to deploy, scale and run Meteor Apps with PM2.
https://github.com/andruschka/pm2-meteor

Last synced: about 2 months ago
JSON representation

Simplest way to deploy, scale and run Meteor Apps with PM2.

Lists

README 

        


  



  



**pm2-meteor** is a CLI tool, that will deploy your Meteor app (from your dev machine or from git) as Nodejs bundle and run it with PM2. (tested with Ubuntu and Freebsd hosts)



## Features

1. you can deploy from a git repo  

2. you can deploy to almost every server construction (also freebsd jails)  

3. it uses PM2 to run your Meteor Apps  

4. reads your Meteor settings file from a path for you    

5. you can configure the directory where your apps will be deployed  

6. you can scale your App in realtime with one command  

7. make generic pm2-meteor settings with a `pm-meteor.js` file which module.exports settings  



### Why PM2?

PM2 is a process manager, that will run/restart Nodejs apps, just like forever - but:

- PM2 has build in load balancing and scaling features

- PM2 also runs bash / python / ruby / coffee / php / perl

- We tested PM2 with some of our complex Meteor apps and it performed well (while forever crashed them without any notable reasons)

- more under [pm2.keymetrics.io](http://pm2.keymetrics.io/)



## Installation (on your dev machine)

```

$ npm i -g pm2-meteor

```

You should have Nodejs, npm and PM2 installed on your host machine.  

pm2-meteor won't install global tools on your server.



## Usage

### 1. Init a pm2-meteor.json config file

```

$ mkdir ninjaApp_deployment

$ cd ninjaApp_deployment

$ pm2-meteor init

```

(The pm2-meteor wizzard will ask you some questions and prefill the configuration file.)



### 2. Complete the generated pm2-meteor.json file

```

{

  // the name of your app

  "appName": "ninjaApp",



  // where your app is located

  "appLocation": {

    "local": "~/Workspace/ninjaApp"

  // or you can also deploy with git ;-)

  // (use username:[email protected]/... for authentication)

  //   "git": "https://user:[email protected]/andruschka/ninjaApp",

  //   "branch": "production"

  },



  // where the meteor settings are located

  "meteorSettingsLocation":"~/Workspace/ninjaApp/settings/production.json",

  "meteorSettingsInRepo": false,

  // or RELATIVE to app root, if settings are located in git repo (this is not a good idea...)

  // "meteorSettingsLocation":"settings/production.json",

  // "meteorSettingsInRepo": true,



  // build flags for Meteor

  "meteorBuildFlags": "--architecture os.linux.x86_64"



  // runs as command in the meteor app before building

  "prebuildScript": "",

  // say you are still using meteorite and want to install deps before deploying:

  // "prebuildScript": "mrt install",



  // the env vars

  // (METEOR_SETTINGS will be generated from your meteor-settings file)

  "env": {

    "ROOT_URL": "http://ninja.my-host.com",

    "PORT": 4004,

    // optional - set some additional free ports if you want to use fork_mode with several instances

    // (you need handle loadbalancing yourself!)

    // "FORK_PORTS": [4005, 4006]

    "MONGO_URL": "mongodb://localhost:27017/ninjaApp"

  },



  // infos for deployment

  "server": {

    "host": "my-host.com",

    "username": "nodejs",

    "password": "trustno1",

    // or auth with pem file

    // "pem":"~/.ssh/id_rsa",

    // optional - set port

    // "port": "22",



    // optional - object whose key and value will be passed as -o key:value to any ssh session

    // "ssh": {} 



    // this dir will contain your apps

    // (app will be deployed to /opt/pm2-meteor/ninjaApp)

    "deploymentDir": "/opt/pm2-meteor",



    // optional - will source a profile before executing tasks on the server

    // "loadProfile": "",



    // exec mode for pm2

    "exec_mode": "cluster_mode",

    "instances": 2,



    // you can also set another interpreter (e.g. use another node version / nvm - see pm2 docs)

    "interpreter": ""

  },

  // optional - set this one if you want to undeploy your app

  // "allowUndeploy": true



  // optional - set this if you want to specify timestamps to the pm2 log-files

  // "log_date_format": "YYYY-MM-DD HH:mm Z"

}

```



### 3. Deploy your app

```

$ pm2-meteor deploy

```

If you already have deployed this app before, the old app tar-bundle will be moved to a ./backup directory.  



##### If you want to only reconfigure settings / env changes

```

$ pm2-meteor reconfig

```

Will send new pm2-env file to server and hard-restart your app.



##### If something goes wrong: revert to previous version

```

$ pm2-meteor revert

```

Will unzip the old bundle.tar.gz and restart the app



### 4. Control your app

```

$ pm2-meteor start

$ pm2-meteor stop

$ pm2-meteor status

$ pm2-meteor logs

```



### 5. SCALE your app

Start 2 more instances:

```

$ pm2-meteor scale +2

```



Down/Upgrade to 4 instances

```

$ pm2-meteor scale 4

```



### 6. Undeploy your app (DANGEROUS)

To delete your app from the PM2 deamon and delete all app files add "allowUndeploy":true to your pm2-meteor setting, then:  

```

$ pm2-meteor undeploy

```



## If you want to deploy the bundle by yourself

```

$ pm2-meteor generateBundle

```

then transfer it to your machine, unzip it and run

```

$ pm2 start pm2-env.json

```

## Example configs

Deploy from a private github repo and start 2 load balanced instances:

```

{

  "appName": "todos",

  "appLocation": {

    "git": "https://andruschka:[email protected]/andruschka/todos.git",

    "branch": "master"

  },

  "meteorSettingsLocation": "settings/production.json",

  "prebuildScript": "mrt install",

  "meteorBuildFlags": "--architecture os.linux.x86_64",

  "env": {

    "PORT": 3000,

    "MONGO_URL": "mongodb://localhost:27017/todos",

    "ROOT_URL": "http://todos.my-host.co"

  },

  "server": {

    "host": "my-host.co",

    "username": "nodejs",

    "pem": "~/.ssh/id_rsa",

    "deploymentDir": "/home/nodejs/",

    "exec_mode": "cluster_mode",

    "instances": 2

  }

}



```



Deploy a local app and run app in fork-mode:  

(using a pm2-meteor.js file and passing the MONGO_URL via bash env var

e.g.: `MONGO_URL='mongodb://user:pw@host/db' pm2-meteor deploy`

)  

```

const appName = "todos"

const mongoUrl = process.env.MONGO_URL



module.exports = {

  appName, // <~ just ES6 stuff for  appName: appName

  "appLocation": {

    "local":"~/Workspace/todos"

  },

  "meteorSettingsLocation": "~/Workspace/todos/settings/production.json",

  "prebuildScript": "",

  "meteorBuildFlags": "--architecture os.linux.x86_64",

  "env": {

    "PORT": 3000,

    "MONGO_URL": mongoUrl, // <~

    "ROOT_URL": "http://todos.my-host.co"

  },

  "server": {

    "host": "my-host.co",

    "username": "nodejs",

    "pem": "~/.ssh/id_rsa",

    "deploymentDir": "/home/nodejs/",

    "exec_mode": "fork_mode",

    "instances": 1

  }

}



```



Deploy a local app and run app in fork-mode with several instances (for managing load balancing yourself):

```

{

  "appName": "todos",

  "appLocation": {

    "local":"~/Workspace/todos"

  },

  "meteorSettingsLocation": "~/Workspace/todos/settings/production.json",

  "prebuildScript": "",

  "meteorBuildFlags": "--architecture os.linux.x86_64",

  "env": {

    "PORT": 3000, // first fork_mode instande willl use this port ...

    "MONGO_URL": "mongodb://localhost:27017/todos",

    "ROOT_URL": "http://todos.my-host.co"

  },

  "server": {

    "host": "my-host.co",

    "username": "nodejs",

    "pem": "~/.ssh/id_rsa",

    "deploymentDir": "/home/nodejs/",

    "exec_mode": "fork_mode",

    "instances": 3,

    "freePorts": [3002, 3003] // ... further fork_mode instances will use this ports

  }

}



```