2018-07-07 11:15:37 +02:00
## Installation
2018-08-17 14:32:14 +02:00
Install [latest Rust ](https://rustup.rs/ ) (1.28+),
2018-08-12 12:35:02 +02:00
[latest Bitcoin Core ](https://bitcoincore.org/en/download/ ) (0.16+)
and [latest Electrum wallet ](https://electrum.org/#download ) (3.2+).
2018-07-07 11:15:37 +02:00
2018-07-15 06:49:23 +02:00
Also, install the following packages (on Debian):
2018-07-07 11:15:37 +02:00
```bash
$ sudo apt update
2018-07-15 06:49:23 +02:00
$ sudo apt install clang cmake # for building 'rust-rocksdb'
2018-07-07 11:15:37 +02:00
```
## Build
First build should take ~20 minutes:
```bash
2018-10-02 05:11:54 +02:00
$ git clone https://github.com/romanz/electrs
$ cd electrs
2018-07-07 11:15:37 +02:00
$ cargo build --release
```
## Bitcoind configuration
Allow Bitcoin daemon to sync before starting Electrum server:
```bash
2018-08-02 13:03:19 +02:00
$ bitcoind -server=1 -txindex=0 -prune=0
2018-07-07 11:15:37 +02:00
```
2018-08-02 13:05:56 +02:00
If you are using `-rpcuser=USER` and `-rpcpassword=PASSWORD` for authentication, please use `--cookie="USER:PASSWORD"` command-line flag.
2018-07-08 21:21:16 +02:00
Otherwise, [`~/.bitcoin/.cookie` ](https://github.com/bitcoin/bitcoin/blob/0212187fc624ea4a02fc99bc57ebd413499a9ee1/contrib/debian/examples/bitcoin.conf#L70-L72 ) will be read, allowing this server to use bitcoind JSONRPC interface.
2018-07-07 11:15:37 +02:00
## Usage
2018-08-17 20:56:02 +02:00
First index sync should take ~1.5 hours:
2018-07-07 11:15:37 +02:00
```bash
2018-08-02 13:05:56 +02:00
$ cargo run --release -- -vvv --timestamp --db-dir ./db [--cookie="USER:PASSWORD"]
2018-08-17 20:56:02 +02:00
2018-08-17T18:27:42 - INFO - NetworkInfo { version: 179900, subversion: "/Satoshi:0.17.99/" }
2018-08-21 17:59:34 +02:00
2018-08-17T18:27:42 - INFO - BlockchainInfo { chain: "main", blocks: 537204, headers: 537204, bestblockhash: "0000000000000000002956768ca9421a8ddf4e53b1d81e429bd0125a383e3636", pruned: false, initialblockdownload: false }
2018-08-17 20:56:02 +02:00
2018-08-17T18:27:42 - DEBUG - opening DB at "./db/mainnet"
2018-08-17T18:27:42 - DEBUG - full compaction marker: None
2018-08-17T18:27:42 - INFO - listing block files at "/home/user/.bitcoin/blocks/blk*.dat"
2018-08-17T18:27:42 - INFO - indexing 1348 blk*.dat files
2018-08-17T18:27:42 - DEBUG - found 0 indexed blocks
2018-08-17T18:27:55 - DEBUG - applying 537205 new headers from height 0
2018-08-17T19:31:01 - DEBUG - no more blocks to index
2018-08-17T19:31:03 - DEBUG - no more blocks to index
2018-08-17T19:31:03 - DEBUG - last indexed block: best=0000000000000000002956768ca9421a8ddf4e53b1d81e429bd0125a383e3636 height=537204 @ 2018-08-17T15:24:02Z
2018-08-17T19:31:05 - DEBUG - opening DB at "./db/mainnet"
2018-08-17T19:31:06 - INFO - starting full compaction
2018-08-17T19:58:19 - INFO - finished full compaction
2018-08-17T19:58:19 - INFO - enabling auto-compactions
2018-08-17T19:58:19 - DEBUG - opening DB at "./db/mainnet"
2018-08-17T19:58:26 - DEBUG - applying 537205 new headers from height 0
2018-08-17T19:58:27 - DEBUG - downloading new block headers (537205 already indexed) from 000000000000000000150d26fcc38b8c3b71ae074028d1d50949ef5aa429da00
2018-08-17T19:58:27 - INFO - best=000000000000000000150d26fcc38b8c3b71ae074028d1d50949ef5aa429da00 height=537218 @ 2018-08-17T16:57:50Z (14 left to index)
2018-08-17T19:58:28 - DEBUG - applying 14 new headers from height 537205
2018-08-17T19:58:29 - INFO - RPC server running on 127.0.0.1:50001
2018-07-07 11:15:37 +02:00
```
2018-10-02 05:11:54 +02:00
If initial sync fails due to `memory allocation of xxxxxxxx bytes failedAborted` errors, as may happen on devices with limited RAM, try the following arguments when starting `electrs` . It should take roughly 18 hours to sync and compact the index on an Odroid HC1 with 8 cpu cores @ 2GHz, 2GB RAM, and an SSD using the following command.
```bash
$ cargo run --release -- -vvvv --index-batch-size=10 --jsonrpc-import --db-dir ./db [--cookie="USER:PASSWORD"]
```
2018-07-07 11:15:37 +02:00
The index database is stored here:
```bash
$ du db/
2018-08-17 21:19:14 +02:00
38G db/mainnet/
2018-07-07 11:15:37 +02:00
```
## Electrum client
```bash
# Connect only to the local server, for better privacy
2018-07-25 11:21:55 +02:00
$ ./scripts/local-electrum.bash
2018-08-15 14:02:24 +02:00
+ ADDR=127.0.0.1
+ PORT=50001
+ PROTOCOL=t
+ electrum --oneserver --server=127.0.0.1:50001:t
< snip >
2018-07-07 11:15:37 +02:00
```
2019-02-23 19:42:15 +01:00
You can persist Electrum configuration (see `~/.electrum/config` ) using:
```bash
$ electrum setconfig oneserver true
$ electrum setconfig server 127.0.0.1:50001:t
$ electrum # will connect only to the local server
```
### SSL connection
2019-01-08 11:44:55 +01:00
In order to use a secure connection, you can also use [NGINX as an SSL endpoint ](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-tcp/# ) by placing the following block in `nginx.conf` .
2018-11-27 23:55:44 +01:00
```nginx
stream {
upstream electrs {
server 127.0.0.1:50001;
}
server {
listen 50002 ssl;
proxy_pass electrs;
2019-01-08 11:44:55 +01:00
ssl_certificate /path/to/example.crt;
ssl_certificate_key /path/to/example.key;
2018-11-27 23:55:44 +01:00
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 4h;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
}
}
```
2019-01-08 11:44:55 +01:00
```bash
$ sudo systemctl restart nginx
$ electrum --oneserver --server=example:50002:s
```
2018-08-20 21:42:58 +02:00
## Docker
```bash
$ docker build -t electrs-app .
$ docker run --network host \
2019-03-02 20:36:13 +01:00
--volume $HOME/.bitcoin:/home/user/.bitcoin:ro \
2018-08-20 21:42:58 +02:00
--volume $PWD:/home/user \
2019-03-02 20:36:13 +01:00
--rm -i -t electrs-app \
electrs -vvvv --timestamp --db-dir /home/user/db
2018-08-20 21:42:58 +02:00
```
2018-07-07 11:15:37 +02:00
## Monitoring
Indexing and serving metrics are exported via [Prometheus ](https://github.com/pingcap/rust-prometheus ):
```bash
$ sudo apt install prometheus
$ echo "
scrape_configs:
- job_name: electrs
static_configs:
2018-08-14 09:13:59 +02:00
- targets: ['localhost:4224']
2018-07-07 11:15:37 +02:00
" | sudo tee -a /etc/prometheus/prometheus.yml
$ sudo systemctl restart prometheus
$ firefox 'http://localhost:9090/graph?g0.range_input=1h& g0.expr=index_height& g0.tab=0'
```