View source for Webmaker/Code/Dev/Environment

__TOC__

=Set up a Webmaker Development Environment=

Before you can test or make improvements to Webmaker, you need to get it running locally.  This involves setting up your OS to host the Webmaker servers and apps, and installing various development tools you'll need.  We strongly recommend a Unix-like OS, such as Linux or OS X, but it is also possible to use Windows.

== Option 1: Installing Webmaker Locally ==
Webmaker can be configured locally to allow for development and testing. This process can be accomplished in a number of ways, but they all require all dependencies to be working before they can succeed.

=== External Dependencies ===
Webmaker relies on a number of technologies and tools, which must first be installed.  The following list needs to be installed and working before you can run or test Webmaker locally, and we provide instructions for doing so on Linux, Mac OS X and Windows below.

* [http://nodejs.org node.js and npm]
* [http://bower.io/ bower]:
* [http://gruntjs.com/ grunt]: 
* [http://www.python.org/ python 2.7]
* [http://www.pip-installer.org/en/latest/installing.html pip]
* [http://www.mongodb.org/downloads MongoDB ] (NOTE: there is some discussion about dropping MongoDB altogether, but at the time of writing, this hasn't happened yet)
* [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java]
* [http://www.elasticsearch.org Elastic Search]
* A working C/C++ toolchain
* A stable build environment for your OS

==== Setting up your dev environment in Mac OS X ====

This is the easiest method of setting up a Webmaker dev environment in Mac OS X, but requires the use of the [http://brew.sh/ Homebrew] package manager. 

# Install [https://developer.apple.com/xcode/ Xcode] command line tools by running <code>xcode-select --install</code> from the terminal
# Install the [http://brew.sh/ Homebrew] package manager by following the instructions at their website.
# Run <code>brew doctor</code> to complete Homebrew's installation
# Install NodeJs with <code>brew install node</code>
# Install the [http://www.oracle.com/technetwork/java/javase/downloads/index.html JDK (Java Development Kit)] from their website
# Install elasticsearch with <code>brew install elasticsearch</code>
# Install mongodb with <code>brew install mongodb</code>

==== Setting up your dev environment  in Ubuntu Linux ====
This is the easiest way to setup a Webmaker dev environment on Ubuntu Linux.

# Install git and a C/C++ toolchain with <code>sudo apt-get -y -q install git g++ make pkg-config</code>
# Install the Java Development Kit with <code>sudo apt-get -y -q install openjdk-7-jre-headless</code>
# Install the MongoDB server
## Install the package with <code>sudo apt-get -y -q install mongodb-server</code>
## Ensure MongoDB is running with <code>service mongodb status</code>
## Otherwise, start MongoDB with <code>sudo service mongodb start</code> 
# Install Elasticsearch 
## Download [http://www.elasticsearch.org/download/ Elasticsearch] as a <code>.deb</code> file and install from the software centre
## Ensure Elasticsearch has started with <code>service elasticsearch status</code>
## Otherwise, start Elasticsearch with <code>sudo service elasticsearch start</code>
# Install Nodejs from Ubuntu PPA
## Add the Node.js PPA using <code>sudo add-apt-repository ppa:chris-lea/node.js</code>
## Update your packages using <code>sudo apt-get update</code>
## Install Node.js using <code>sudo apt-get install nodejs</code>

==== Setting up your dev environment in Fedora Linux ====

# Install git and a C/C++ toolchain with <code>sudo yum install -y git gcc-c++ make pkgconfig</code>
# Install the Java Development Kit with <code>sudo yum install -y java-1.7.0-openjdk-headless</code>
# Install the MongoDB server
## Install the package with <code>sudo yum install -y mongodb-server</code>
# Install Elasticsearch 
## Download [http://www.elasticsearch.org/download/ Elasticsearch] as a <code>.rpm</code> file and install it with <code>sudo rpm -i elasticsearch*.rpm</code>
## You may need to run a few commands:
### <code> sudo /bin/systemctl daemon-reload</code>
### <code>sudo /bin/systemctl enable elasticsearch.service</code>
## You can then start it with <code>sudo /bin/systemctl start elasticsearch.service</code>
# Install Nodejs  with <code>sudo yum install -y nodejs npm</code>

==== Setting up your dev environment  in Windows 7 ====
Our [https://github.com/mozilla/webmaker-suite Webmaker-suite npm module] has excellent documentation on preparing a Windows development environment. You can find it [http://mozilla.github.io/webmaker-suite/windows.html here].

=== NodeJS dependencies ===
If you followed the Windows-specific external-dependency instructions, this step has already been completed. Otherwise, once your Development environment is set up, you must install some global NPM packages.

# Install [http://bower.io/ bower] with <code>sudo npm install -g bower</code>
# Install [http://gruntjs.com/ grunt] with <code>sudo npm install -g grunt</code>
# Install grunt-cli with <code>sudo npm install -g grunt-cli</code>

=== Installing Webmaker Option 1: Webmaker-suite ===
By far the easiest way to get all of Webmaker set up and installed locally, on any platform, is to use [https://github.com/mozilla/webmaker-suite Webmaker Suite].  This is a set of automation scripts written in node.js by one of our lead developers, and is meant to provide turn-key installation by automatically downloading all the code, and setting default environment variables.

Complete instructions are available in the [https://github.com/mozilla/webmaker-suite#webmaker-suite-bootstrapinstallation-script README for Webmaker Suite] on github.

=== Installing Webmaker Option 2: Manual Installation ===
Each server that makes up a part of the Webmaker.org ecosystem is configured with <code>.env</code> or ''environment'' files. The servers come with a sample version of this file that is fully functional, assuming that the sample files are used for all the servers in the local installation.  Instructions on configuring these manually can be found in the Github repository of each server.   

==== Installing Webmaker Core ====
Webmaker's core apps are the ''Login'', ''MakeAPI'' and ''Webmaker.org'' servers.  These three must be run together in order to function properly with each other, and the other apps that make up Webmaker.  You can find installation instructions in the <code>readme</code> file in each server's Github repository:

* '''Login''' - [https://github.com/mozilla/login.webmaker.org/blob/master/README.md https://github.com/mozilla/login.webmaker.org/blob/master/README.md]
* '''MakeAPI''' - [https://github.com/mozilla/MakeAPI/blob/master/README.md https://github.com/mozilla/MakeAPI/blob/master/README.md]
* '''Webmaker.org''' - [https://github.com/mozilla/webmaker.org/blob/master/README.md https://github.com/mozilla/webmaker.org/blob/master/README.md]

==== Installing Webmaker Tools ====
Webmaker's tools (''Thimble'', ''Goggles'' and ''Popcorn Maker'') follow similar procedures for installation and configuration.  Keep in mind that they won't function properly without the '''Webmaker Core''' services running. You can find installation instructions in the <code>readme</code> file in each server's Github repository:

* '''Popcorn Maker''' - [https://github.com/mozilla/popcorn.webmaker.org/blob/master/README.md https://github.com/mozilla/popcorn.webmaker.org/blob/master/README.md]
* '''Thimble''' - [https://github.com/mozilla/thimble.webmaker.org/blob/master/README.md https://github.com/mozilla/thimble.webmaker.org/blob/master/README.md]
* '''Goggles''' - [https://github.com/mozilla/goggles.webmaker.org/blob/master/README.md https://github.com/mozilla/goggles.webmaker.org/blob/master/README.md]

=== Staying Up-to-date ===
As we improve features (day-to-day), we release them into the wild almost immediately! For this reason, it's important to keep your servers running the latest code. 

==== Webmaker-suite ====
Follow the update instructions listed in the [https://github.com/mozilla/webmaker-suite#updating-the-suite Webmaker-suite README section on the topic].

==== Manual installation ====
Each server will need to be updated separately, though the process is identical.

These commands use <code>git</code> to pull the latest updates from the Mozilla repo, and then reinstall the node ''modules'' (or libraries).  If you followed each server's installation instructions exactly, <code>[mozilla upstream remote]</code> should be replaced with <code>origin</code>.  Otherwise, replace it with whatever you labeled the Mozilla [http://git-scm.com/book/en/Git-Basics-Working-with-Remotes git remote]. 

* Dirty update (try this first): <code>git checkout master && git pull [mozilla upstream remote] master && npm install</code>
* Clean update (time intensive) <code>git checkout master && git pull [mozilla upstream remote] master && rm -rf node_modules && npm cache clear && npm install</code>

== Option 2: Installing Webmaker on Heroku ==
TODO

== Option 3: Installing Webmaker with Vagrant ==

'''NOTE:''' This is a work in progress, and may have bugs.  See https://github.com/mozilla/webmaker-suite for more info on using webmaker-suite itself.

* Download and install vagrant first ( http://www.vagrantup.com/downloads.html )
* Download the Vagrantfile from [https://github.com/mozilla/webmaker-suite/blob/aws-vagrant/vagrant/localdev/Vagrantfile github] into a folder where you want to run your webmaker-suite VM from (ie, <code>/Users/myuser/vagrant/webmaker-suite</code>).
* Open a terminal, cd into that folder, and issue the command <code>vagrant up</code>. This will download the current version box (this is an Ubuntu 1.7gb image and may take a while).
* Once complete building, issue the command <code>vagrant ssh</code> to ssh in your new vagrant box.
* Now in vagrant, issue the command <code>./webmaker-suite.sh</code>. This will start mongo, elasticsearch, webmaker, popcorn, thimble, makeapi, goggles, etc.

After it completes, point your web browser to:
* http://127.0.0.1:3000 - login.webmaker.org
* http://127.0.0.1:3500 - thimble.webmaker.org
* http://127.0.0.1:5000 - makeapi
* http://127.0.0.1:5050 - htmlsanitizer.org
* http://127.0.0.1:7777 - webmaker.org
* http://127.0.0.1:8888 - popcorn.webmaker.org
* http://127.0.0.1:12416 - goggles.webmaker.org

More detailed information available [https://github.com/mozilla/webmaker-suite/tree/aws-vagrant/vagrant/localdev/README.md here].

Example Output:

<pre>
localmac-23:24:58-imagetest# vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
[default] Box 'webmakersuitev3test' was not found. Fetching box from specified URL for
the provider 'virtualbox'. Note that if the URL does not have
a box for this provider, you should interrupt Vagrant now and add
the box yourself. Otherwise Vagrant will attempt to download the
full box prior to discovering this error.
Downloading or copying the box...
<1.7gb of downloading occurs here>
Successfully added box 'webmakersuitev3test' with provider 'virtualbox'!
[default] Importing base box 'webmakersuitev3test'...
[default] Matching MAC address for NAT networking...
[default] Setting the name of the VM...
[default] Clearing any previously set forwarded ports...
[default] Creating shared folders metadata...
[default] Clearing any previously set network interfaces...
[default] Preparing network interfaces based on configuration...
[default] Forwarding ports...
[default] -- 22 => 2222 (adapter 1)
[default] -- 3000 => 3000 (adapter 1)
[default] -- 3500 => 3500 (adapter 1)
[default] -- 5000 => 5000 (adapter 1)
[default] -- 5050 => 5050 (adapter 1)
[default] -- 7777 => 7777 (adapter 1)
[default] -- 8888 => 8888 (adapter 1)
[default] -- 12416 => 12416 (adapter 1)
[default] Booting VM...
[default] Waiting for machine to boot. This may take a few minutes...
[default] Machine booted and ready!
[default] Mounting shared folders...
[default] -- /vagrant
localmac-23:42:19-imagetest# vagrant ssh
Welcome to Ubuntu 12.04 LTS (GNU/Linux 3.2.0-23-generic x86_64)
 * Documentation:  https://help.ubuntu.com/
Welcome to your Vagrant-built virtual machine.
Last login: Fri Jan 17 20:52:50 2014 from 10.0.2.2
vagrant@precise64:~$ ./webmaker-suite.sh
</pre>