`ripple-rest`

A RESTful API for submitting payments and monitoring accounts on the Ripple Network.

See the API Reference for details on the available endpoints and supported data formats.

Installing and Running

ripple-rest requires PostgreSQL for production systems but supports in-memory sqlite3 for testing.

Running using in-memory SQLite3

Run git clone git@github.com:ripple/ripple-rest.git to clone repository
Run npm install to install dependencies
Run node server.js to start the server
Visit http://localhost:5990 to view available endpoints and to get started

Note that restarting the server will delete the database so this CANNOT BE USED IN PRODUCTION.

Running in a Virtual Machine

On Linux

Run git clone https://github.com/ripple/ripple-rest.git in a terminal and switch into the ripple-rest directory
cp config-example.json config.json and configure DATABASE_URL appropriately
Run npm install to install the dependencies and setup the database
Run node server.js to start the server
Visit http://localhost:5990/api/v1/status in your browser to confirm that the server is up and running

On Mac OSX

Install Fig and dependencies listed on that page
Install VirtualBox
Run docker-osx shell (not needed on Linux)
Run fig up or, on OSX, PYTHONIOENCODING=utf-8 fig up to start virtual machine
Visit http://localdocker:5990 to view available endpoints and to get started

Running with an existing PostgreSQL Installation

Run git clone git@github.com:ripple/ripple-rest.git to clone repository
Set the DATABASE_URL environment variable to point to your (configured and running) PostgreSQL instance. You can temporarily set the environment variable by running export DATABASE_URL=postgres://{user}:{password}@{host}:{port}/{database}. That variable can be more permanently set by adding the export line your shell configuration (default is $HOME/.bashrc) or to /etc/environment.
Run npm install to install dependencies and run database migrations
Run node server.js to start the server
Visit http://localhost:5990 to view available endpoints and to get started

Note that if npm install fails because the user running it does not have sufficient permissions to access and modify the database, the command ./node_modules/.bin/grunt must be run with sufficient permissions to execute database migrations.

Configuring `ripple-rest`

The ripple-rest server loads configuration options from the following sources, according to the following hierarchy (where options from 1. override those below it):

Command line arguments
Environment variables
The config.json file

The path to the config.json file can be specified as a command line argument (node server.js --config /path/to/config.json). If no path is specified, the default location for that file is in ripple-rest's root directory.

Available configuration options are outlined in the Server Configuration document and an example configuration file is provided here.

ripple-rest uses the nconf configuration loader so that any options that can be specified in the config.json file can also be specified as command line arguments or environment variables.

Running `ripple-rest` Securely

Prerequisites

Install as small and lightweight a systemware build as possible. The Base system package set is ideal. Only install additional packages to support specific installation or maintenance objectives.
At a minimum, install all extant security patches, and configure the server to do so on an ongoing basis (daily, ideally).
Before installing the REST API server, harden the machine using industry best practices. For example, see How to secure an Ubuntu 12.04 LTS server - Part 1 The Basics, Ubuntu Security, CIS Debian Linux Benchmark v1.0.0.
Use only strong passwords, a minimum of 16 characters with a mix of capital and lowercase letters, numbers, and symbols. For more on password security see Dropbox: realistic password strength estimation

Installing `ripple-rest`

Install ripple-rest into a directory tree owned by the root user. We use /opt.
Create a service account that the ripple-rest instance will run as. It should NOT have a home directory because an attacker could potentially make use of that for a point-in-time attack.

sudo useradd -U -m -r -s /dev/null restful

Create a database that the ripple-rest server will store its back-end datain. Also create a database service account which only has access to that database:

sudo -u postgres createdb gateway_appliance
sudo -u postgres createuser appliance -E -S -R -D
sudo -u postgres psql -c "ALTER USER appliance PASSWORD '<strong password here>';"

Create SSL certificate to encrypt traffic to and from the ripple-rest server. Ensure that all associated files are mode 0644 so that the service account can access them. To mitigate the potential harm done by making those files accessible, proactively limit the number of people who can log into that machine.

openssl genrsa -out /etc/ssl/private/server.key 2048
openssl req -utf8 -new -key /etc/ssl/private/server.key -out /etc/ssl/server.csr -sha512
  -batch
openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/server.key
  -out /etc/ssl/certs/server.crt -sha512

When starting the ripple-rest server itself, start it as the service account:

cd /opt/ripple-rest
sudo -E -u restful /usr/bin/node server.js

emschwartz/ripple-rest

ripple-rest