This website is no longer actively supported. Please see the Ripple Developer Center for up-to-date documentation and other resources.

Ripple Client

From Ripple Wiki
Jump to: navigation, search

Overview

Ripple Trade is an open-source, online JavaScript client that provides a simple way to access and use the Ripple Consensus Ledger. Unlike many web-based money systems, most of Ripple Trade's operations happen locally in the browser, and it connects directly to public rippled servers over a secure connection. User information is encrypted in the browser and stored securely in the Blobvault such that user details cannot be retrieved unilaterally by the operator of the server, nor by malicious users who gain unauthorized access to the servers.

The Ripple Knowledge Center contains lots of additional information about using Ripple Trade.


Developing the Client

This section is intended for developers and explains how to rebuild the JavaScript files and deployment packages.

Get code

To check out the ripple client, simply clone the git repository:

git clone https://github.com/ripple/ripple-client.git

Before you can use the client, you need to compile the JavaScript and CSS. Please refer to the section "Building" below to learn how to do that.

Building ripple-client

The Ripple client has a pure Node.js build system based on Grunt.

First, Ensure that Node.js is installed using the instructions supplied with node.js due to the fact that the version of node.js offered officially is often too old to install the necessary dependencies. If you ran the unit tests on rippled, you should have gone through this process already.

Install ripple-client's dependencies:

cd /path/to/ripple-client
npm install

Install Grunt to build the client:

npm install -g grunt-cli

Build the client:

grunt

Note: If you get the error "/usr/bin/env: node: No such file or directory", it may be a misnaming error. The executable may be called nodejs instead of node, so you just need to symlink it (sudo ln -s /usr/bin/nodejs /usr/bin/node) to fix the problem. Then try running the grunt command again.

Configuration

To configure the client, make a copy of the config-example.js file and call it config.js. You can then edit it and fill in the settings you'd like the client to use. Some settings can later be overridden by each individual user.

Once configured, you should be able to run the debug version of the client by opening index_debug.html in a web browser. We recommend you use a webserver if you can, rather than opening the HTML using file://.

Advanced building

Two versions

There are two versions of the client, debug and live. The debug version can be accessed by opening index_debug.html. It links to those JavaScript source files that are optimized for debugging.

The live version is accessible via index.html and links to the minified JavaScript sources.

Live Building

If you're making lots of changes, building may get tedious. To make grunt watch for changes and build automatically, run:

grunt ; grunt watch

Live Reload

It's nice when making changes in CSS to see the new style without reloading the whole app. Livereload can do this for you.

Common setup

To enable livereload, add this to your config.js:

document.write('<script src="https://github.com/livereload/livereload-js/raw/master/dist/livereload.js?snipver=1&host='
               + (location.host || 'localhost').split(':')[0]
               + '"></script>');

We recommend you download livereload.js and change the URL above to point to your local copy, which will load more quickly and put less strain on Github's servers.

Our grunt watch build target is LiveReload enabled, so if you're running grunt watch, you have an instant built-in LiveReload server.

Guard

If for some reason the built-in Livereload server does not work for you, you can alternatively try guard and guard-livereload:

gem install guard
gem install guard-livereload

Have guard running while developing:

cd /path/to/ripple-client
guard

Make sure you turn off the default built-in LiveReload (by editing Gruntfile.js.)

Configuring

Copy the configuration file:

cp config-example.js config.js

Customize config.js as needed.

Serving the client

Setup

Before setup, make sure you checkout a stable version of the client from the official git repository. You also need to follow the instructions under "Building" above to compile the client.

Files

The following files/directories need to be deployed to your webserver:

  • build/
  • compat/
  • deps/js/modernizr-2.5.3.min.js
  • fonts/
  • img/
  • index.html
  • swf/

The following file represents configuration and should be created or otherwise set up.

  • config.js (copy config-example.js)

Rebranding the client

Security

Please follow these instructions carefully, any mistakes may severely compromise your users' security.

Webserver

Make sure the web server is as secure as possible. If insecure, the client served may be altered to be malicious. A malicious client could steal secrets and money.

Here is a non-exhaustive list of security recommendations:

  • Serve the client from a separate server.
  • Serve the client on a separate domain or subdomain than any other page, API or website.
  • Only serve the client via HTTPS to avoid it being modified in transit. You can reply to HTTP requests, but only to redirect to HTTPS.
  • This server should run a webserver (80 and 443), anything needed for server maintenance and nothing else.
  • The client is 100% static files. The webserver should only have a minimal setup of essential modules. (No PHP (!), DAV, etc.)
  • Mind the security at your hosting company. Many attacks against Bitcoin businesses were social engineering attacks against the hosting company's support infrastructure.
  • Mind the server's physical security.

HTTPS Strict Transport Security

Enable HTTPS STS for at least the subdomain that the client is served on.

http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security

Clickjacking

Set the header: X-FRAME-OPTIONS DENY

See: https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet

Downloadable Client

A guide to using the downloadable client is available on the Ripple Labs Help Center.