more gatewayd revisions

gatewayd.md

@@ -1,10 +1,10 @@
 # gatewayd #
 
-Gatewayd (pronounced "gateway-dee"), also known as the Ripple Gateway Framework, provides the basic functionality of a gateway on the Ripple Network, so that you can extend it to build your own gateway. The system includes a core database that manages accounting for deposits and withdrawals of assets to the Ripple network. Gatewayd provides a standard interface for issuing any currency on the Ripple network and exchange, with the goal of completely abstracting interaction with Ripple.
+Gatewayd (pronounced "gateway-dee"), provides a framework you can extend to build a gateway on the Ripple Network. The system includes a core database that manages accounting for deposits and withdrawals of assets, linking the network with your holdings in the outside world. Gatewayd provides a standard interface for issuing any currency on the Ripple network and exchange, with the goal of completely abstracting interaction with Ripple.
 
 Interact with the gatewayd by building custom integrations with banking and payment systems around the world, and by using the built-in APIs for designing beautiful gateway mobile apps and user interfaces. A HTTP/JSON server, Javascript library, and commandline interface are provided as interfaces to the gatewayd software.
 
-The Ripple Gateway's features include: 
+Gatewayd's features include: 
 
   - user registration 
   - deposits and withdrawals
@@ -15,22 +15,29 @@ The Ripple Gateway's features include:
 
 ## Dependencies
 
-1. Node.js
+1. [Node.js](http://nodejs.org/)
   - The express web module is used to serve HTTP/JSON endpoints
   - A Basic Auth strategy is used for authentication of users, admin.
   - Several NPM modules must be globally installed: db-migrate, pg, forever, and mocha
 
-2. Postgres
+2. [Postgres](http://www.postgresql.org/)
   - The easiest way to get started with Postgres is by launching a [free database hosted by Heroku](https://postgres.heroku.com/databases)
   - For local development on Mac the simplest installation is via the [Postgres App](http://postgresapp.com/) by Heroku.
-  - On Ubuntu, [install and configure Postgres](https://help.ubuntu.com/community/PostgreSQL) using the aptitude package manager and the psql tool.
+  - On Linux, you can generally install Postgres from your distro's package manager. See instructions for:
+    - [Ubuntu](https://help.ubuntu.com/community/PostgreSQL)
+    - [Debian](http://www.postgresql.org/download/linux/debian/)
+    - [Red Hat, Fedora, CentOS](http://www.postgresql.org/download/linux/redhat/)
+    - [SuSE](http://www.postgresql.org/download/linux/suse/)
+    - [Arch Linux](https://wiki.archlinux.org/index.php/Postgres)
 
 3. [Ripple REST API](https://github.com/ripple/ripple-rest.git)
   - The Ripple REST API provides a simplified HTTP/JSON interface to all the Ripple protocol network operations, such as payments and other transactions.
 
+4. [git](http://git-scm.com/) is required for installation and updating. It is not used during general operation.
+
 ## Installation
 
-The gateway server software requires git, g++, make, nodejs, postgres, and several npm modules.
+Installing gatewayd requires git, g++, make, nodejs, postgres, and several npm modules. 
 
 - Comprehensive [installation script](https://github.com/ripple/gatewayd/blob/master/doc/install.md) for Ubuntu
 
@@ -38,10 +45,26 @@ The gateway server software requires git, g++, make, nodejs, postgres, and sever
 
 Once ripple-gateway is installed, [configure your gateway](https://github.com/ripple/gatewayd/blob/master/doc/setup.md) wallets and server
 
+## Updating
+
+The update process for gatewayd may change in the future, but for now, updating to a new version follows this process:
+
+<span class='draft-comment'>(Not totally sure about the commandline syntax for all of these</span>
+
+1. Use git to pull the `master` branch [from Github](https://github.com/ripple/gatewayd.git). (This assumes you created it by using `git clone` on the repository first.)<br/>
+    `git pull`
+2. Install any new npm modules needed by the new version<br/>
+    `sudo npm install --global`
+3. Disable the current gateway processes. (This starts downtime)<br/>
+    `pm2 kill`
+4. Apply schema changes to the database, if the new version includes any.<br/>
+    `grunt migrate`
+5. Restart the gatewayd processes. (This ends downtime)<br/>
+    `bin/gateway start`
 
 # Gatewayd Usage #
 
-## Running the Ripple Gateway
+## Running gatewayd
 
 After installation, start the gateway processes by running the command:
 
@@ -130,6 +153,55 @@ API calls: list_withdrawals, clear_withdrawal
 Alternatively one can provide a WITHDRAWALS_CALLBACK_URL in the configuration, and then start the withdrawal_callbacks process to receive POST notifications whenever a new withdrawal comes in the gateway from the Ripple network. This process is currently not starte by default.
 
 
+## Command Line Interface ##
+
+```
+bin/gateway [options] [command]
+```
+
+The available *options* are as follows:
+
+```
+-h, --help     output usage information
+```
+  
+The available commands are as follows:
+  
+| Command Syntax | Description |
+|----------------|-------------|
+| `register_user <username> <password> <ripple_address> ` | create a user with a ripple address |
+| `list_users` | list registered users |
+| `record_deposit <amount> <currency> <external_account_id>` | record a deposit in the deposit processing queue |
+| `list_deposits` | list deposits in the deposit processing queue |
+| `list_outgoing_payments` | list the outgoing ripple payments. |
+| `list_incoming_payments` | list unprocesses incoming ripple payments |
+| `list_withdrawals` | get pending withdrawals to external accounts |
+| `clear_withdrawal <external_transaction_id>` | clear pending withdrawal to external account |
+| `generate_wallet` | generate a random ripple wallet |
+| `set_hot_wallet <address> <secret>` | set the gateway hot wallet |
+| `get_hot_wallet` | get the address of the gateway hot wallet |
+| `get_hot_wallet_secret` | get the secret of the gateway hot wallet |
+| `fund_hot_wallet <amount> <currency>` | issue funds from cold wallet to hot wallet |
+| `set_cold_wallet <account>` | set the gateway hot wallet |
+| `get_cold_wallet` | get the gateway cold wallet |
+| `refund_cold_wallet <amount> <currency>` | send back funds from the hot wallet to cold wallet |
+| `set_trust <amount> <currency>` | set level of trust from hot to cold wallet |
+| `get_trust_lines` | get the trust lines from hot wallet to cold wallet |
+| `list_currencies` | List all currencies supported by the gateway |
+| `add_currency <currency>` | add support for a currency |
+| `remove_currency <currency>` | remove support for a currency |
+| `set_domain <domain>` | set the domain name of the gateway |
+| `get_domain` | get the domain name of the gateway |
+| `set_postgres_url <url>` | set the url of the postgres database |
+| `get_postgres_url` | get the url of the postgres database |
+| `set_ripple_rest_url <url>` | set the url of the Ripple-REST api |
+| `get_ripple_rest_url` | get the url of the Ripple-REST api |
+| `set_key` | set the admin api key |
+| `get_key` | get the admin api key |
+| `set_last_payment_hash <hash>` | set the last encountered payment hash for incoming processing. |
+| `get_last_payment_hash` | get the last encountered payment hash for incoming processing. |
+    
+
 # Gatewayd API #
 
 `gatewayd : v3.20.0`
@@ -188,7 +260,7 @@ Alternatively one can provide a WITHDRAWALS_CALLBACK_URL in the configuration, a
 * [`POST /v1/start`](#starting-worker-processes)
 * [`POST /v1/processes`](#listing-current-processes)
 
-# API Overview #
+# API Method Reference #
 
 ## Managing Users ##
 
@@ -1305,17 +1377,17 @@ new key.
 Request Body:
 
 ```
-    {
+{
   "key": "1234578dddd"
-    }
+}
 ```
 
 Response Body:
 
 ```
-    {
+{
   "KEY": "1234578dddd"
-    }
+}
 ```
 
 ### Retrieve API Key ###
@@ -1326,9 +1398,9 @@ This method shows the gateway API key currently in use.
 Response Body:
 
 ```
-    {
+{
   "KEY": "ebdb883d5723a71c59fb8ecefbb65476a6923f2a69b49b53cffe212c817cab92"
-    }
+}
 ```
 
 ### List Supported Currencies ###
@@ -1337,12 +1409,15 @@ __`GET /v1/currencies`__
 List currencies supported by the gateway, which are shown in the gateway's ripple.txt
 manifest file.
 
-    RESPONSE:
+Response Body:
-    {
+
+```
+{
   "CURRENCIES": {
     "SWD": 10000
   }
-    }
+}
+```
 
 ### Set Supported Currencies ###
 __`POST /v1/currencies`__
@@ -1350,19 +1425,24 @@ __`POST /v1/currencies`__
 Add a currency to be supported by the gateway. This currency is shown in the gateway's
 ripple.txt manifest file.
 
-    REQUEST:
+Request Body:
-    {
-      currency: "XAG"
-    }
 
-    RESPONSE:
+```
-    {
+{
+  currency: "XAG"
+}
+```
+
+Response Body
+
+```
+{
   "CURRENCIES": {
     "SWD": 10000,
     "XAG": 0
   }
-    }
+}
-
+```
 ## Managing Gateway Processes ##
 
 ### Start Worker Processes ###
@@ -1376,8 +1456,10 @@ __`GET /v1/processes`__
 
 List information about the currently-running gateway daemon processes.
 
-    RESPONSE:
+Response Body:
-    [ { pid: 26269,
+
+```
+[ { pid: 26269,
     name: 'ripplerest',
     pm2_env: 
      { name: 'ripplerest',
@@ -1622,52 +1704,5 @@ List information about the currently-running gateway daemon processes.
        status: 'stopped' },
     pm_id: 5,
     monit: { memory: 0, cpu: 0 } } ]
-
-# Command Line Interface #
-
-```
-bin/gateway [options] [command]
 ```
 
-The available *options* are as follows:
-
-```
--h, --help     output usage information
-```
-  
-The available commands are as follows:
-  
-| Command Syntax | Description |
-|----------------|-------------|
-| `register_user <username> <password> <ripple_address> ` | create a user with a ripple address |
-| `list_users` | list registered users |
-| `record_deposit <amount> <currency> <external_account_id>` | record a deposit in the deposit processing queue |
-| `list_deposits` | list deposits in the deposit processing queue |
-| `list_outgoing_payments` | list the outgoing ripple payments. |
-| `list_incoming_payments` | list unprocesses incoming ripple payments |
-| `list_withdrawals` | get pending withdrawals to external accounts |
-| `clear_withdrawal <external_transaction_id>` | clear pending withdrawal to external account |
-| `generate_wallet` | generate a random ripple wallet |
-| `set_hot_wallet <address> <secret>` | set the gateway hot wallet |
-| `get_hot_wallet` | get the address of the gateway hot wallet |
-| `get_hot_wallet_secret` | get the secret of the gateway hot wallet |
-| `fund_hot_wallet <amount> <currency>` | issue funds from cold wallet to hot wallet |
-| `set_cold_wallet <account>` | set the gateway hot wallet |
-| `get_cold_wallet` | get the gateway cold wallet |
-| `refund_cold_wallet <amount> <currency>` | send back funds from the hot wallet to cold wallet |
-| `set_trust <amount> <currency>` | set level of trust from hot to cold wallet |
-| `get_trust_lines` | get the trust lines from hot wallet to cold wallet |
-| `list_currencies` | List all currencies supported by the gateway |
-| `add_currency <currency>` | add support for a currency |
-| `remove_currency <currency>` | remove support for a currency |
-| `set_domain <domain>` | set the domain name of the gateway |
-| `get_domain` | get the domain name of the gateway |
-| `set_postgres_url <url>` | set the url of the postgres database |
-| `get_postgres_url` | get the url of the postgres database |
-| `set_ripple_rest_url <url>` | set the url of the ripple rest api |
-| `get_ripple_rest_url` | get the url of the ripple rest api |
-| `set_key` | set the admin api key |
-| `get_key` | get the admin api key |
-| `set_last_payment_hash <hash>` | set the last encountered payment hash for incoming processing. |
-| `get_last_payment_hash` | get the last encountered payment hash for incoming processing. |
-