deployment doc

# Deploying A MapRoulette Server

Deploying a MapRoulette instance is pretty straightforward. We have a Fabric script that takes care of almost everything for you. 

If you just want to run MapRoulette locally for development or testing, this guide is not for you.

## What do you need? ##

You need a server to deploy MapRoulette on. This can be a local or remote machine, but it will need to meet these requirements:

* Debian flavored linux (tested on Ubuntu 12.04LTS and 13.10)
* Access to that machine with a sudo-enabled account

## Clone the Github repo ##

On your local machine, clone the MapRoulette repo:

    git clone [email protected]:osmlab/maproulette

## Prepare your local environment ##



    cd maproulette
    mkvirtualenv maproulette
    pip install -r requirements.txt

## Deploy ##

You are now ready to start deploying. This should be a one-liner:

    fab deploy:INSTANCE_NAME,hosts=HOST

`INSTANCE_NAME` is the name used on the server to designate your MapRoulette instance. This can be any string, but it is suggested to use the fully qualified domain name the MapRoulette server will be accessible as, for example `maproulette.example.com`.

`HOST` is where we going to deploy this instance, for example `[email protected]`, where `user` needs to be a user with sudo rights.

This process will take up to 15 minutes, because a good number of packages need to be downloaded and installed or compiled, files put into place, services restarted, etcetera.

Once it finishes without error, you should be able to go to `http://maproulette.example.org/` and see MapRoulette in your browser. You are not quite there yet though! 

## Final steps ##

We need some final tweaks to the server configuration, which we can't do using Fabric because they contain non-public information.

### MapRoulette configuration file ###

Log on to your server and open `/srv/www/INSTANCE_NAME/config.py` in a text editor.

You will need to edit three parts in this file:

#### OAuth ####

You will need to enter the OAuth consumer key and consumer secret that identifies your MapRoulette instance on OpenStreetMap. If you haven't yet, you need to register your MapRoulette instance at your OpenStreetMap OAuth settings: go to [OSM](http://osm.org/), log in, go to 'My Settings' and then to 'oauth settings', and follow the steps to register a new application.

Once you have done that, you will see your application's OAuth details, including the consumer key and consumer secret. 

Carry those over to this part of the configuration file:

    OSM = {
	    ....
        'consumer_key': '',
        'consumer_secret': ''
    }

#### Default Challenge ####

You will need to tell your instance what the default challenge is your users will see. Challenges are identified by their slug. 

Find this section and replace 'test1' with your desired default challenge's slug:

    DEFAULT_CHALLENGE = 'test1'

_If you don't have a challenge loaded yet (likely) you will want to make sure to come back to this step later._

#### Mailgun API key ####

MapRoulette uses a third party mail service that takes the hassle out of sending emails from your server. It's called Mailgun and it is free for basic use. The only place this is used right now is for emailing the MapRoulette instance administrator (you) when a challenge gets depleted.

To use mailgun, you will need to sign up on their web site to get your API key. You can the carry this key over to 

    MAILGUN_API_KEY = 'REPLACE WITH YOUR MAILGUN API KEY'

_If you don't want to use this functionality, you can easily comment out the relevant lines in `maproulette/api/__init__.py`. We intend to make this a configuration option in the future. Pull request welcome._

### nginx Configuration ###

_This is only necessary if you named your instance differently from your MapRoulette server's FQDN._

Log on to your server and open `/etc/nginx/sites-available/INSTANCE_NAME` in a text editor.

Notice the block where it says 

     ## Only requests to our Host are allowed
     if ($host !~ ^({{instance}})$ ) {
        return 444;
     }

This will block any requests that are not made to a host name that does not contain `instance`. You will need to adapt this to only allow requests to your FQDN, or disable this security measure altogether at your own risk by commenting out these three lines.