Awesome

The Uploader API powers the Uploader Interface by issuing authentication tokens and receiving imagery uploads. Before proceeding, we suggest you read the ecosystem docs.

Installation and Usage

The steps below will walk you through setting up your own instance of the oam-uploader-api.

Install Project Dependencies

• MongoDB
• Node.js v0.12

Using homebrew, you can install MongoDB and other dependencies:

$ brew bundle

Install Application Dependencies

If you use nvm, activate the desired Node version:

nvm install

Install Node modules:

npm install

Usage

You need to set environment variables before starting the API. We suggest you copy local.sample.env to local.env and modify it. Before starting the API you can run source local.env to export the environment variables to the shell.

Environment Variables

• NODE_ENV - Node environment. When in production should be set to production, otherwise can be ignored.
• PORT - The port to listen on (Default to 4000).
• HOST - The hostname or ip address (Default to 0.0.0.0).
• COOKIE_PASSWORD - Password used for cookie encoding. Should be at least 32 characters long. IMPORTANT to change the default one for production.
• AWS_ACCESS_KEY_ID - AWS secret key id for reading OIN_BUCKET.
• AWS_SECRET_ACCESS_KEY - AWS secret access key for reading OIN_BUCKET.
• AWS_REGION - AWS region of OIN_BUCKET (Default to us-west-2).
• SENDGRID_API_KEY - Sendgrid API key, for sending notification emails.
• SENDGRID_FROM - Email address from which to send notification emails (Default to info@hotosm.org).
• OIN_BUCKET - The OIN bucket that will receive the uploads (Default to oam-uploader).
• DBURI - MongoDB connection url (Default to mongodb://localhost/oam-uploader)
• DBURI_TEST - MongoDB connection url for tests. Will be loaded when NODE_ENV is test. It's not needed for production. (Default to mongodb://localhost/oam-uploader-test)
• ADMIN_USERNAME - Username to access the Token Management panel.
• ADMIN_PASSWORD - Password to access the Token Management panel.
• GDRIVE_KEY - Google Api key. Needed to use the upload from google drive functionality.
• GDAL_TRANSLATE_BIN - Full path to the gdal bin (Default to /usr/bin/gdal_translate)
• MAX_WORKERS - Max number of workers used to process the uploads (Default to 1)
• NEW_RELIC_LICENSE_KEY - New relic license key.
• TILER_BASE_URL - Base URL for dynamic TMS/WMTS endpoints. Defaults to http://tiles.openaerialmap.org.

For a quick local setup for development the following variables can be omitted: SENDGRID_API_KEY, SENDGRID_FROM, GDRIVE_KEY, NEW_RELIC_LICENSE_KEY. Be aware that although the system will work some functionalities will not be available and errors may be triggered.

Starting the database

mongod

Starting the API:

npm start

The API exposes endpoints used to access information form the system via a RESTful interface.

Tokens

The uploader endpoints are protected via a token authentication system. Tokens are issued using the oam-uploader-admin, a friendly user interface for token management. Follow the instructions to set it up. To understand better how all the components interact refer to the Ecosystem Docs.

Populate the database

To get the API running quickly, you can skip running the admin interface and populate the database with a test token.

mongo
use oam-uploader
db.tokens.insert(
  {
    "name" : "admin",
    "expiration" : false,
    "status" : "active",
    "token" : "MYTESTTOKEN",
    "created" : ISODate("2016-12-15T17:28:19.823Z"),
    "updated" : null
  }
)

Documentation

The documentation for the different endpoints can be generated by running:

npm run docs

This will compile the documentation and place it inside docs. The docs site can then be run by any web server.

The documentation is also automatically built and deployed by Travis CI whenever a Pull Request is merged to the production branch (in this case master). The deployment is done to gh-pages.

Install via Docker

Alternatively, if you've got a mongo instance running elsewhere, install and run on a fresh instance using docker as follows:

Install Docker

One-time setup:

# clone the repo
git clone https://github.com/hotosm/oam-uploader-api

# build the docker image
cd oam-uploader-api
docker build -t oam-uploader-api .

# set up environment vars:
cp local.sample.env local.env
nano local.env

To start up the API server after pulling from the repo:

# install node dependencies
.build_scripts/docker/run.sh /install.sh
# start server
.build_scripts/docker/run.sh /start.sh

Deployment

To automate some of the above on a remote, you can use visionmedia/deploy and upstart for deployment and process management.

First, add a new section to https://github.com/hotosm/oam-uploader-api/blob/develop/.build_scripts/deploy.conf. (If you don't want to commit it to the repo, you can just make your own copy of the config file wherever you want.) Make sure you have ssh creds to the server from wherever you're running deploy. Then do the following, with ENV replaced with whatever you called the section you added to deploy.conf.

deploy -c .build_scripts/deploy.conf ENV setup

Now ssh into the server with deploy -c .build_scripts/deploy.conf ENV console, and set up the upstart script and start up the server

sudo cp .build_scripts/upstart.conf /etc/init/oam-uploader-api.conf
sudo nano /etc/init/oam-uplodaer-api.conf
sudo start oam-uploader-api
exit

Now you can use deploy -c .build_scripts/deploy.conf ENV at any time to deploy your local branch.

License

Oam Uploader Api is licensed under BSD 3-Clause License, see the LICENSE file for more details.