Webmaker/Code/Dev/Environment

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 dependancies to be working before they can succeed.

External Dependancies

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.

• node.js and npm
• bower:
• grunt:
• python 2.7
• pip
• MongoDB (NOTE: there is some discussion about dropping MongoDB altogether, but at the time of writing, this hasn't happened yet)
• Java
• 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 Homebrew package manager.

1. Install Xcode command line tools by running xcode-select --install from the terminal
2. Install the Homebrew package manager by following the instructions at their website.
3. Run brew doctor to complete Homebrew's installation
4. Install NodeJs with brew install node
5. Install the JDK (Java Development Kit) from their website
6. Install elasticsearch with brew install elasticsearch
7. Install mongodb with brew install mongodb

Setting up your dev environment in Ubuntu Linux

This is the easiest way to setup a Webmaker dev environment on Ubuntu Linux, but requires that NodeJS be compiled from source.

1. Install git and a C/C++ toolchain with sudo apt-get -y -q install git g++
2. Install the Java Development Kit with sudo apt-get -y -q install openjdk-7-jre-headless
3. Install the MongoDB server
   1. Install the package with sudo apt-get -y -q install mongodb-server
   2. Ensure MongoDB is running with service mongodb status
   3. Otherwise, start MongoDB with sudo service mongodb start
4. Install Elasticsearch
   1. Download Elasticsearch as a .deb file and install from the software centre
   2. Ensure Elasticsearch has started with service elasticsearch status
   3. Otherwise, start Elasticsearch with sudo service elasticsearch start
5. Install Nodejs from source
   1. Clone Node using git clone git://github.com/ry/node.git`
   2. Navigate to the new directory with cd node
   3. Checkout the latest stable version of Nodejs (currently v0.10.22) with git checkout v0.10.22
   4. Run ./configure
   5. Run make > output.txt
   6. Run sudo make install > output.txt

Setting up your dev environment in Fedora Linux

TODO

Setting up your dev environment in Windows 7

Our Webmaker-suite npm module has excellent documentation on preparing a Windows development environment. You can find it here.

NodeJS dependancies

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.

1. Install bower with sudo npm install -g bower
2. Install grunt with sudo npm install -g grunt

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 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 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 .env 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 readme file in each server's Github repository:

• Login - https://github.com/mozilla/login.webmaker.org/blob/master/README.md
• MakeAPI - https://github.com/mozilla/MakeAPI/blob/master/README.md
• Webmaker.org - 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 readme file in each server's Github repository:

• Popcorn Maker - https://github.com/mozilla/popcorn.webmaker.org/blob/master/README.md
• Thimble - https://github.com/mozilla/thimble.webmaker.org/blob/master/README.md
• Goggles - 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 Webmaker-suite README section on the topic.

Manual installation

Each server will need to updated separately, though the process is identical.

These commands use git 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, [mozilla upstream remote] should be replaced with origin. Otherwise, replace it with whatever you labeled the Mozilla git remote.

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

Option 2: Installing Webmaker on Heroku

TODO

Option 3: Installing Webmaker with Vagrant

TODO