This installation guide walks through the process of installing Plunker and all its components, assuming they are all running on the same server. Tested on Ubuntu 12 LTS.
Plunker is made up of several component repositories (taken from the plunker documentation):
- plunker_api The server that connects to a mongodb database and serves requests over a restful api.
- plunker_www The server that is responsible for hosting and running the front-end that users see and touch everyday.
- plunker_run The server that allows for previewing of plunks and temporary previews and also does the dynamic transpilation.
- plunker_collab The server that serves the code necessary for collaborative coding as well as doing the actual operational transformation over a browserchannel connection.
- plunker_embed The server that hosts the embedded views of plunks.
Some components require special attention; this guide will walk you through a successfull install of all components, assuming the following versions:
- plunker_api@9370605fa6d73db18a450cb11e02a730633d9b02
- plunker_www@4785ffd0f95450effd0ce8062bce7f22a6f3318b
- plunker_run@fd72c304eff55a7b9726803883bd9f9eb0798409
- plunker_collab@22d82620fa7541858533f96394ac521b00043229
- plunker_embed@c56e3b4aea283d6bed9314dc40c33e869c52f674
##Installation
sudo apt-get install python-software-properties python g++ make
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
###Plunker Configuration Files
Each plunker component uses its own configuration file, usually config.production.json or config.development.json depending on the environment.
The environment is defined by the process.env.NODE_ENV towards the top of the server.js file of each component.
Below is a table of the configuration files required for each component, and reference to examples attached to this gist:
| Component | Config Filename | Example Filename |
|---|---|---|
| plunker_api | config.<env>.json |
config.api.example.json |
| plunker_www | config.<env>.json |
config.www.example.json |
| plunker_run | config.<env>.json |
config.run.example.json |
| plunker_collab | config.<env>.json |
config.collab.example.json |
| plunker_embed | config.json |
config.embed.example.json |
Currently,there is a problem where the "port" configuration value is lowercase in the example configuration files, but should be uppercase "PORT". Be sure to change this, or the port value set in the configuration files will not take effect (See Issue #58).
The configuration file values for the URLs for each Plunker component should be duplicated (and identical) between all the configuration files, but the "PORT" should be changed to reflect each component.
###Installing plunker_api
First, clone the repository to the specified version:
git clone https://github.com/filearts/plunker_api.git
cd plunker_api
git checkout 9370605fa6d73db18a450cb11e02a730633d9b02
Next, install node dependencies:
npm install
Install and configure mongodb:
sudo apt-get install mongodb
mongo
> use plunker
> db.addUser("DB_USERNAME", "DB_PASSWORD")
> exit
Be sure to modify the configuration file settings for the plunker_api configuration file to match your mongodb settings.
###Installing plunker_www First, clone the repository to the specified version:
git clone https://github.com/filearts/plunker_www.git
cd plunker_www
git checkout 4785ffd0f95450effd0ce8062bce7f22a6f3318b
Next, install node dependencies:
npm install
###Installing plunker_run First, clone the repository to the specified version:
git clone https://github.com/filearts/plunker_run.git
cd plunker_run
git checkout fd72c304eff55a7b9726803883bd9f9eb0798409
Next, install node dependencies:
npm install
###Installing plunker_collab First, clone the repository to the specified version:
git clone https://github.com/filearts/plunker_collab.git
cd plunker_collab
git checkout 22d82620fa7541858533f96394ac521b00043229
Edit package.json and change the ShareJS dependency tarball to point to version 0.6:
https://github.com/share/ShareJS/archive/v0.6.0.tar.gz
Install node dependencies:
npm install
###Installing plunker_embed First, clone the repository to the specified version:
git clone https://github.com/filearts/plunker_embed.git
cd plunker_embed
git checkout c56e3b4aea283d6bed9314dc40c33e869c52f674
Install node dependencies:
npm install
Note: plunker_embed looks for config.json NOT config.<env>.json
##Deployment ###Enabling Github Authentication
Visit the Github Application Settings page and create a new application to represent your installation of Plunker.
Your callback URL is /auth/github; the full value should look something like: http://plunk.example.com/auth/github
Take note of your Client ID and Client Secret, and distribute these values into all of your Plunker configuration files.
Note: All Set; but you may need to restart Plunker.
###Deploying under Apache2 using mod-proxy
This is my preferred method of deployment, and the only one I have tested with.
First, enable mod_proxy:
sudo a2enmod proxy_http
Next, create a new apache VirtualHost configuration for your Plunker installation (use the attached apache-vhost-example.conf as a template).
Then restart apache:
sudo service apache2 restart
Plunker should now be accessible from behind apache.
###Running Plunker On Startup
The most straightforward way to run Plunker on startup is using init.d scripts. For node.js applications, I highly recommend using initd-forever:
sudo npm install forever -g
sudo npm install initd-forever -g
And to generate an init.d script for each plunker component, just run:
initd-forever -a /path/to/your/plunker_www/server.js
. . .
initd-forever -a /path/to/your/plunker_embed/server.js
Depending on your environment, this may give you some trouble. You may need to reference the full path to the forever binary (see output of which forever), and/or cd into the node.js application path.
For an example of my configuration, see the attached upstart_example.sh.
###Unknown Server Error for Thumbnails
Plunker generates webpage thumbnails using the immediatenet thumbnail API, which doesn't support URLs containing port numbers (Ex. run.example.com:8004). You may see this error:
Thumbnails are generated from the plunker_run component, which in this tutorial is running at run.example.com:8004. In order to make use of the immediatenet thumbnail API, another Apache VirtualHost can be added so that ProxyPass directs all requests to run.example.com to run.example.com:8004.