Webmaker/Code/Dev/EnvironmentGuide

From MozillaWiki
< Webmaker‎ | Code
Jump to: navigation, search

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.

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:

  • node.js and npm
  • bower: after you install npm, you can type npm install -g bower (may require admin/sudo rights)
  • grunt: after you install npm, type npm install -g grunt-cli (may require admin/sudo rights)
  • 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 number of node "modules" (or libraries) that we use also require a working C/C++ toolchain. You should make sure that you have a working build environment for your OS (see the section of the Webmaker Suite docs on this issue).

Setup 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.

Note that this won't install external dependancies above automatically.

Complete instructions are available in the README for Webmaker Suite on github.

Setup Option 2: Local Native 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.

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

Set up NodeJS dependancies

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 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:

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:

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. These commands will 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 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

Setup Option 3: Using Vagrant (i.e., Ubuntu-based VM)

TODO

Setup Option 4: Heroku

TODO

Retrieved from "https://wiki.mozilla.org/index.php?title=Webmaker/Code/Dev/EnvironmentGuide&oldid=785890"