Windows And Webmaker Events

Webmaker is a very large project, with dozens of parts that all come together at https://webmaker.org. One of the hardest things for new contributors is getting everything set up properly. This problem multiplies ten-fold when the desired platform of the developer is Windows. Recently, I put together a guide for a new contributor, explaining the steps it takes to set up a Windows 7 computer for development of Webmaker projects (specifically, the events platform). It's a long, complicated, and frustrating process, which I'd like to share here, so that should anyone need to do this, they won't have to look very far.

Dependency Installation

Git

We use Git for version control, and Github for hosting our code repos publicly.

You can install Git from http://git-scm.com/download/win. That site should automatically prompt you to download the latest version of Git available for Windows. Once it is downloaded, run the executable to begin the installation. I used all the default settings.

Node

Basically all of Webmakers servers are written in JavaScript, and use NodeJS.

Download the latest installation executable from http://nodejs.org/download and run the installer once the download completes. Node Package Manager (npm) will be installed as well.

Python

Some modules included as dependencies will require Python 2.7 to be installed.

You can download the installer from https://www.python.org/download/releases/2.7.8/. During the installation make sure to specify that you want python.exe added to your PATH.

Visual Studio 2010

This is where things get stupid. Npm depends on something called node-gyp, a so-called "cross-platform" tool for compiling native addons. The problem is, its a pain in the ass to get it running on a Windows machine. I'll share what I did to get it running, but in the end, you might have to do something different, depending on your machine.

Installing the four items above didn't quite cut it for me though. Here's the last few steps I took:

  • I ran git bash (you can find it in your start menu) and ran the command npm install -g node-gyp to install the node-gyp package globally.

  • I then opened the file C:\Users\cade\.node-gyp\0.10.29 \common.gypi - obviously, substitute your username and the version of node-gyp you install.

  • The file contains configuration settings in JSON format. Navigate to target_defaults.msvs_settings.VCLinkerTool and add 'AdditionalLibraryDirectories': 'c:\\Program Files\\Microsoft SDKs\\Windows\\v7.1\\Lib\\x64', to the object VCLinkerTool

If you're as lucky as I was, node-gyp might now work for you!

Grunt-cli and bower

Grunt is a task runner, used maily for building resources. Bower is a front-end package manager. We're going to install these globally using npm, so that the grunt and bower commands will be added to your PATH, making life easier. To do this run: npm install -g grunt-cli bower

Setting up Webmaker Events

Login.webmaker.org

This is the Login server for webmaker. It manages Webmaker accounts through the Login API, and is required for log-in functionality to work. The code can be found at https://github.com/mozilla/login.webmaker.org

  1. In Git Bash, change into the directory you would like to clone the code into.

  2. Run git clone https://github.com/your_user_name/login.webmaker.org to clone your fork of the code to your machine. Git will set your Github fork up as the remote named "origin", so you can push code changes and branches back up to the website.

  3. Change into the login.webmaker.org folder and run cp env.sample .env. This will create a configuration file for the server from the default one provided in the repo. It's configured to work "out of the box" with other Webmaker sites and services you will run locally.

  4. Now we need to install npm and bower dependencies. Do this by running npm install; bower install

  5. You should now be able to start the server with node app. If Windows prompts you to grant permissions for Node, accept them.

Events Front End

This is the Front-End for The Webmaker Events platform. It's an Angular app that is served using Express. The source code is at https://github.com/mozilla/webmaker-events-2. Don't ask about webmaker-events, we don't talk about it anymore.

  1. In Git Bash, change into the directory you would like to clone the code into.

  2. Run git clone https://github.com/your_user_name/webmaker-events-2 to clone your fork of the code to your machine. Git will set your Github fork up as the remote named "origin", so you can push code changes and branches back up to the website.

  3. Change into the webmaker-events-2 folder and run cp .env-dist .env. This will create a configuration file for the server from the default one provided in the repo. It's configured to work "out of the box" with other Webmaker sites and services you will run locally.

  4. Now we need to install npm and bower dependencies. Do this by running npm install; bower install

  5. Before we can run the server we need to compile the CSS. Do so by running grunt build

  6. You should now be able to start the server with node server/server.js. If Windows prompts you to grant permissions for Node, accept them.

Events Service

This is the Events API, which provides RESTful read/write access to the events database. The source code can be found at https://github.com/mozilla/webmaker-events-service.

  1. In Git Bash, change into the directory you would like to clone the code into.

  2. Run git clone https://github.com/your_user_name/webmaker-events-service to clone your fork of the code to your machine. Git will set your Github fork up as the remote named "origin", so you can push code changes and branches back up to the website.

  3. Change into the webmaker-events-service folder and run cp .env-dist .env. This will create a configuration file for the server from the default one provided in the repo. It's configured to work "out of the box" with other Webmaker sites and services you will run locally.

  4. Now we need to install the npm dependencies. Do this by running npm install

  5. You should now be able to start the server with node server/server.js. If Windows prompts you to grant permissions for Node, accept them.

Summary

Developing on windows with NPM sucks, but it's not impossible. If the above helped, I'm glad. The steps for the above set-ups for login, events and the events-service can be applied to most other Webmaker sites and tools. Be sure to always check the README files for details about set-up and running a particular project.