diff --git a/README.md b/README.md index a0e588b..1a1923a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ front-end and LevelDB for storage. ## Prerequisites -* Node.js v0.10.x - Download and Install [Node.js](http://www.nodejs.org/download/). +* **Node.js v0.10.x** - Download and Install [Node.js](http://www.nodejs.org/download/). You can also follow [this gist](https://gist.github.com/isaacs/579814) for a quick and easy way to install Node.js and npm. If you use Ubuntu: @@ -20,15 +20,16 @@ make make install ``` -* Bitcoind - Download and Install [Bitcoin](http://bitcoin.org/en/download) -- You should make sure to configure RPC security and `txindex`. -The easiest way to do this is copying `./etc/bitcoind/bitcoin.conf` to your -bitcoin directory (usually ~/.bitcoin). +* **bitcoind** - Download and Install [Bitcoin](http://bitcoin.org/en/download) -- Bitcoind must be running and must have finished downloading the blockchain *BEFORE* starting Insight. +Configure bitcoind to listen to RPC calls and set `txindex` to true. +The easiest way to do this is by copying `./etc/bitcoind/bitcoin.conf` to your +bitcoin data directory (usually `"~/.bitcoin"` on Linux, `"%appdata%\Bitcoin\"` on Windows, +and `"~/Library/Application Support/Bitcoin"` on Mac OS X). -### Tools -* NPM - Node.js package manager, should be installed when you install node.js. +bitcoind must be running and must have finished downloading the blockchain *BEFORE* running Insight. + +* **NPM** - Node.js package manager, should be automatically installed when you get node.js. ## Quick Install To install Insight, clone the main repository: @@ -38,15 +39,22 @@ bitcoin directory (usually ~/.bitcoin). Install dependencies: $ npm install + + Run the main application: + $ node insight.js Then open a browser and go to: http://localhost:3000 + + Please note that the app will need to sync its internal database + with the blockchain state, which may take some time. You can check + sync progress from within the web interface. ## Configuration -All configuration is specified in the [config](config/) folder, particularly the [config.js](config/config.js) file. Here you will need to specify your application name and database name. +All configuration is specified in the [config](config/) folder, particularly the [config.js](config/config.js) file. Here you can specify your application name and database name. ### bitcoind @@ -55,25 +63,28 @@ There is a bitcoind configuration sample at: etc/bitcoind/bitcoin.conf ``` -If you need to configure bitcoind server access set the following environment variables: +If you need to use a custom bitcoind server set the following environment variables: ``` -BITCOIND_HOST -BITCOIND_PORT # RPC Bitcoind Port -BITCOIND_P2P_PORT # P2P Bitcoind Port +BITCOIND_HOST # RPC bitcoind host +BITCOIND_PORT # RPC bitcoind Port +BITCOIND_P2P_PORT # P2P bitcoind Port BITCOIND_USER # RPC username BITCOIND_PASS # RPC password BITCOIND_DATADIR # bitcoind datadir for livenet, or datadir/testnet3 for testnet INSIGHT_NETWORK [= 'livenet' | 'testnet'] ``` -Make sure that bitcoind is configured to accept incomming connections using 'rpcallowip' decribed in https://en.bitcoin.it/wiki/Running_Bitcoin. Alternatively change `config/env/$NODE_ENV.js` +If you use this option, make sure that bitcoind is configured to accept incoming connections using 'rpcallowip' as described in https://en.bitcoin.it/wiki/Running_Bitcoin. -In case the network is changed, levelDB database need to be deleted. This can be performed running: +Alternatively, change `config/env/$NODE_ENV.js` + +In case the network is changed, levelDB database needs to be deleted. This can be performed running: ```util/sync.js -D``` -and waiting to Insight to synchronize again. The process can be interrupted and continued from the synchronization process embedded in main app insight.js safely. +and waiting for Insight to synchronize again. +Once the database is deleted, the process can be safely interrupted (CTRL+C) and continued from the synchronization process embedded in main app. -### Environment Variables Settings +## Environment Variables Settings There are three environments provided by default, __development__, __test__, and __production__. Each of these environments has the following configuration options: @@ -93,7 +104,7 @@ To run insight locally for development: $ NODE_ENV=development grunt -## Other utilities for development +### Other utilities for development To compile and minify the web application's assets: ```grunt compile``` @@ -102,12 +113,12 @@ To run the tests ### Production -You can use [pm2](https://github.com/Unitech/pm2) to manage NodeJS in production: +You can use [pm2](https://github.com/Unitech/pm2) to manage the NodeJS app in production: $ npm install pm2 -g $ pm2 start insight.js -[forever] (https://github.com/nodejitsu/forever) can also be used for this task. +[forever] (https://github.com/nodejitsu/forever) can also be used for this purpose. ## DB storage requirement @@ -115,21 +126,17 @@ To store the blockchain and address related information, Insight uses LevelDB. T stored on /db (this can be changed on config/config.js). As of February 2014, storing the blockchain takes ~31Gb of disk space on levelDB, -and Insight needs ~7hrs to complete the syncronization process. +and Insight needs ~10 minutes to complete the syncronization process on testnet. ## Syncing old blockchain data - Old blockchain data can be synced manually from Insight (to save blocks and transactions in - LevelDB): + Old blockchain data can be manually synced from Insight: - Create folders: - - $ mkdir -p db/blocks $ utils/sync.js -S Check utils/sync.js --help for options, particulary -D to erase the current DB. - *NOTE* that there is no need to run this manually since the historic syncronization is embedded on the webserver, so running the webserver will trigger the historic sync. + *NOTE* that there is no need to run this manually since the historic syncronization is embedded on the web application, so by running you will trigger the historic sync automatically. ## API @@ -191,10 +198,9 @@ Sample output: Sample output: ``` { - "__v":0, "hash":"000000004a3d187c430cd6a5e988aca3b19e1f1d1727a50dead6c8ac26899b96", "time":1389789343, - "fromP2P":true, + ... } ```