From 9753af1fedc61f1320de2ef6abdd30a229ec14fb Mon Sep 17 00:00:00 2001
From: hunicus <93150691+hunicus@users.noreply.github.com>
Date: Tue, 3 May 2022 00:01:20 -0400
Subject: [PATCH] Move docker docs to ./docker/readme + edit
---
README.md | 319 +++++---------------------------------------
docker/README.md | 334 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 364 insertions(+), 289 deletions(-)
create mode 100644 docker/README.md
diff --git a/README.md b/README.md
index 1b061b41a..70b147b36 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,14 @@ Mempool can be self-hosted on a wide variety of your own hardware, ranging from
We support the following installation methods, ranked in order from simple to advanced:
1) [One-click installation on full-node distros](#one-click-installation)
-2) [Docker installation on Linux using docker-compose](#docker-installation)
+2) [Docker installation on Linux using docker-compose](./docker/README.md)
3) [Manual installation on Linux or FreeBSD](#manual-installation)
-4) [Production installation on a powerful FreeBSD server](https://github.com/mempool/mempool/tree/master/production)
+4) [Production installation on a powerful FreeBSD server](./production/README.md)
+
+This doc offers install notes on the one-click method and manual install method. Follow the links above for install notes on Docker and production installations.
-### One-click installation on full-node distros
+### One-Click Installation
Mempool can be conveniently installed on the following full-node distros:
- [Umbrel](https://github.com/getumbrel/umbrel)
@@ -27,278 +29,12 @@ Mempool can be conveniently installed on the following full-node distros:
- [myNode](https://github.com/mynodebtc/mynode)
- [Start9](https://github.com/Start9Labs/embassy-os)
-# Docker Installation
+
+### Manual Installation
-The `docker` directory contains the Dockerfiles used to build and release the official images and a `docker-compose.yml` file that is intended for end users to run a Mempool instance with minimal effort.
+The following instructions are for a manual installation on Linux or FreeBSD. You may need to change file and directory paths to match your OS.
-## bitcoind only configuration
-
-To run an instance with the default settings, use the following command:
-
-```bash
-$ docker-compose up
-```
-
-The default configuration will allow you to run Mempool using `bitcoind` as the backend, so address lookups will be disabled. It assumes you have added RPC credentials for the `mempool` user with a `mempool` password in your `bitcoin.conf` file:
-
-```
-rpcuser=mempool
-rpcpassword=mempool
-```
-
-If you want to use your current credentials, update them in the `docker-compose.yml` file:
-
-```
- api:
- environment:
- MEMPOOL_BACKEND: "none"
- RPC_HOST: "172.27.0.1"
- RPC_PORT: "8332"
- RPC_USER: "mempool"
- RPC_PASS: "mempool"
-```
-
-Note: the IP in the example above refers to Docker's default gateway IP address so the container can hit the `bitcoind` instance running on the host machine. If your setup is different, update it accordingly.
-
-You can check if the instance is running by visiting http://localhost - the graphs will be populated as new transactions are detected.
-
-## bitcoind+electrum configuration
-
-In order to run with a `electrum` compatible server as the backend, in addition to the settings required for running with `bitcoind` above, you will need to make the following changes to the `docker-compose.yml` file:
-
-- Under the `api` service, change the value of the `MEMPOOL_BACKEND` key from `none` to `electrum`:
-
-```
- api:
- environment:
- MEMPOOL_BACKEND: "none"
-```
-
-- Under the `api` service, set the `ELECTRUM_HOST` and `ELECTRUM_PORT` keys to your Docker host IP address and set `ELECTRUM_TLS_ENABLED` to `false`:
-
-```
- api:
- environment:
- ELECTRUM_HOST: "172.27.0.1"
- ELECTRUM_PORT: "50002"
- ELECTRUM_TLS_ENABLED: "false"
-```
-
-You can update any of the backend settings in the `mempool-config.json` file using the following environment variables to override them under the same `api` `environment` section.
-
-JSON:
-```
- "MEMPOOL": {
- "NETWORK": "mainnet",
- "BACKEND": "electrum",
- "HTTP_PORT": 8999,
- "SPAWN_CLUSTER_PROCS": 0,
- "API_URL_PREFIX": "/api/v1/",
- "POLL_RATE_MS": 2000,
- "CACHE_DIR": "./cache",
- "CLEAR_PROTECTION_MINUTES": 20,
- "RECOMMENDED_FEE_PERCENTILE": 50,
- "BLOCK_WEIGHT_UNITS": 4000000,
- "INITIAL_BLOCKS_AMOUNT": 8,
- "MEMPOOL_BLOCKS_AMOUNT": 8,
- "PRICE_FEED_UPDATE_INTERVAL": 600,
- "USE_SECOND_NODE_FOR_MINFEE": false,
- "EXTERNAL_ASSETS": ["https://raw.githubusercontent.com/mempool/mining-pools/master/pools.json"],
- "STDOUT_LOG_MIN_PRIORITY": "info"
- },
-```
-
-docker-compose overrides:
-```
- MEMPOOL_NETWORK: ""
- MEMPOOL_BACKEND: ""
- MEMPOOL_HTTP_PORT: ""
- MEMPOOL_SPAWN_CLUSTER_PROCS: ""
- MEMPOOL_API_URL_PREFIX: ""
- MEMPOOL_POLL_RATE_MS: ""
- MEMPOOL_CACHE_DIR: ""
- MEMPOOL_CLEAR_PROTECTION_MINUTES: ""
- MEMPOOL_RECOMMENDED_FEE_PERCENTILE: ""
- MEMPOOL_BLOCK_WEIGHT_UNITS: ""
- MEMPOOL_INITIAL_BLOCKS_AMOUNT: ""
- MEMPOOL_MEMPOOL_BLOCKS_AMOUNT: ""
- MEMPOOL_PRICE_FEED_UPDATE_INTERVAL: ""
- MEMPOOL_USE_SECOND_NODE_FOR_MINFEE: ""
- MEMPOOL_EXTERNAL_ASSETS: ""
- MEMPOOL_STDOUT_LOG_MIN_PRIORITY: ""
-```
-
-JSON:
-```
-"CORE_RPC": {
- "HOST": "127.0.0.1",
- "PORT": 8332,
- "USERNAME": "mempool",
- "PASSWORD": "mempool"
- },
-```
-docker-compose overrides:
-```
- CORE_RPC_HOST: ""
- CORE_RPC_PORT: ""
- CORE_RPC_USERNAME: ""
- CORE_RPC_PASSWORD: ""
-```
-
-JSON:
-```
- "ELECTRUM": {
- "HOST": "127.0.0.1",
- "PORT": 50002,
- "TLS_ENABLED": true
- },
-```
-
-docker-compose overrides:
-```
- ELECTRUM_HOST: ""
- ELECTRUM_PORT: ""
- ELECTRUM_TLS: ""
-```
-
-JSON:
-```
- "ESPLORA": {
- "REST_API_URL": "http://127.0.0.1:3000"
- },
-```
-docker-compose overrides:
-```
- ESPLORA_REST_API_URL: ""
-```
-
-JSON:
-```
- "SECOND_CORE_RPC": {
- "HOST": "127.0.0.1",
- "PORT": 8332,
- "USERNAME": "mempool",
- "PASSWORD": "mempool"
- },
-```
-
-docker-compose overrides:
-```
- SECOND_CORE_RPC_HOST: ""
- SECOND_CORE_RPC_PORT: ""
- SECOND_CORE_RPC_USERNAME: ""
- SECOND_CORE_RPC_PASSWORD: ""
-```
-
-JSON:
-```
- "DATABASE": {
- "ENABLED": true,
- "HOST": "127.0.0.1",
- "PORT": 3306,
- "DATABASE": "mempool",
- "USERNAME": "mempool",
- "PASSWORD": "mempool"
- },
-```
-
-docker-compose overrides:
-```
- DATABASE_ENABLED: ""
- DATABASE_HOST: ""
- DATABASE_PORT: ""
- DATABASE_DATABASE: ""
- DATABASE_USERAME: ""
- DATABASE_PASSWORD: ""
-```
-
-JSON:
-```
- "SYSLOG": {
- "ENABLED": true,
- "HOST": "127.0.0.1",
- "PORT": 514,
- "MIN_PRIORITY": "info",
- "FACILITY": "local7"
- },
-```
-
-docker-compose overrides:
-```
- SYSLOG_ENABLED: ""
- SYSLOG_HOST: ""
- SYSLOG_PORT: ""
- SYSLOG_MIN_PRIORITY: ""
- SYSLOG_FACILITY: ""
-```
-
-JSON:
-```
- "STATISTICS": {
- "ENABLED": true,
- "TX_PER_SECOND_SAMPLE_PERIOD": 150
- },
-```
-
-docker-compose overrides:
-```
- STATISTICS_ENABLED: ""
- STATISTICS_TX_PER_SECOND_SAMPLE_PERIOD: ""
-```
-
-JSON:
-```
- "BISQ": {
- "ENABLED": false,
- "DATA_PATH": "/bisq/statsnode-data/btc_mainnet/db"
- }
-```
-
-docker-compose overrides:
-```
- BISQ_ENABLED: ""
- BISQ_DATA_PATH: ""
-```
-
-JSON:
-```
- "SOCKS5PROXY": {
- "ENABLED": false,
- "HOST": "127.0.0.1",
- "PORT": "9050",
- "USERNAME": "",
- "PASSWORD": ""
- }
-```
-
-docker-compose overrides:
-```
- SOCKS5PROXY_ENABLED: ""
- SOCKS5PROXY_HOST: ""
- SOCKS5PROXY_PORT: ""
- SOCKS5PROXY_USERNAME: ""
- SOCKS5PROXY_PASSWORD: ""
-```
-
-JSON:
-```
- "PRICE_DATA_SERVER": {
- "TOR_URL": "http://wizpriceje6q5tdrxkyiazsgu7irquiqjy2dptezqhrtu7l2qelqktid.onion/getAllMarketPrices",
- "CLEARNET_URL": "https://price.bisq.wiz.biz/getAllMarketPrices"
- }
-```
-
-docker-compose overrides:
-```
- PRICE_DATA_SERVER_TOR_URL: ""
- PRICE_DATA_SERVER_CLEARNET_URL: ""
-```
-
-# Manual Installation
-
-The following instructions are for a manual installation on Linux or FreeBSD. The file and directory paths may need to be changed to match your OS.
-
-## Dependencies
+Dependencies:
* [Bitcoin](https://github.com/bitcoin/bitcoin)
* [Electrum](https://github.com/romanz/electrs)
@@ -306,9 +42,10 @@ The following instructions are for a manual installation on Linux or FreeBSD. Th
* [MariaDB](https://github.com/mariadb/server)
* [Nginx](https://github.com/nginx/nginx)
-## Mempool
+#### Get Latest Mempool Release
Clone the mempool repo, and checkout the latest release tag:
+
```bash
git clone https://github.com/mempool/mempool
cd mempool
@@ -316,20 +53,22 @@ Clone the mempool repo, and checkout the latest release tag:
git checkout $latestrelease
```
-## Bitcoin Core (bitcoind)
+#### Configure Bitcoin Core
Enable RPC and txindex in `bitcoin.conf`:
+
```bash
rpcuser=mempool
rpcpassword=mempool
txindex=1
```
-## MySQL
+#### Get & Configure MySQL
+
+Install MariaDB from your OS package manager:
-Install MariaDB from OS package manager:
```bash
- # Linux
+ # Debian, Ubuntu, etc.
apt-get install mariadb-server mariadb-client
# macOS
@@ -338,6 +77,7 @@ Install MariaDB from OS package manager:
```
Create database and grant privileges:
+
```bash
MariaDB [(none)]> drop database mempool;
Query OK, 0 rows affected (0.00 sec)
@@ -349,7 +89,8 @@ Create database and grant privileges:
Query OK, 0 rows affected (0.00 sec)
```
-## Mempool Backend
+#### Build Mempool Backend
+
Install mempool dependencies from npm and build the backend:
```bash
@@ -365,7 +106,8 @@ In the `backend` folder, make a copy of the sample config and modify it to fit y
cp mempool-config.sample.json mempool-config.json
```
-Edit `mempool-config.json` to add your Bitcoin Core node RPC credentials:
+Edit `mempool-config.json` with your Bitcoin Core node RPC credentials:
+
```bash
{
"MEMPOOL": {
@@ -401,7 +143,7 @@ Start the backend:
npm run start
```
-When it's running you should see output like this:
+When it's running, you should see output like this:
```bash
Mempool updated in 0.189 seconds
@@ -424,9 +166,9 @@ When it's running you should see output like this:
Updating mempool
```
-## Mempool Frontend
+#### Build Mempool Frontend
-Install mempool dependencies from npm and build the frontend static HTML/CSS/JS:
+Install the Mempool dependencies with npm and build the frontend:
```bash
# frontend
@@ -435,15 +177,15 @@ Install mempool dependencies from npm and build the frontend static HTML/CSS/JS:
npm run build
```
-Install the output into nginx webroot folder:
+Install the output into the nginx webroot folder:
```bash
sudo rsync -av --delete dist/ /var/www/
```
-## nginx + certbot
+#### `nginx` + `certbot`
-Install the supplied nginx.conf and nginx-mempool.conf in /etc/nginx
+Install the supplied `nginx.conf` and `nginx-mempool.conf` in `/etc/nginx`:
```bash
# install nginx and certbot
@@ -457,7 +199,6 @@ Install the supplied nginx.conf and nginx-mempool.conf in /etc/nginx
```
-If everything went okay you should see the beautiful mempool :grin:
+If everything went well, you should see the beautiful mempool :grin:
-If you get stuck on "loading blocks", this means the websocket can't connect.
-Check your nginx proxy setup, firewalls, etc. and open an issue if you need help.
+If you get stuck on "loading blocks", this means the websocket can't connect. Check your nginx proxy setup, firewalls, etc. and open an issue if you need help.
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 000000000..da7bf20e3
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,334 @@
+# Docker Installation
+
+This directory contains the Dockerfiles used to build and release the official images and a `docker-compose.yml` for end users to run a Mempool instance with minimal effort.
+
+You can choose to configure Mempool to run with a basic backend powered by just `bitcoind`, or with `bitcoind` along with an Electrum-compatible server for full functionality.
+
+## `bitcoind`-only Configuration
+
+_Note: address lookups require an Electrum server and will not work with this configuration._
+
+Make sure `bitcoind` is running and synced.
+
+The default Docker configuration assumes you have added RPC credentials for a `mempool` user with a `mempool` password in your `bitcoin.conf` file, like so:
+
+```
+rpcuser=mempool
+rpcpassword=mempool
+```
+
+If you want to use different credentials, specify them in the `docker-compose.yml` file:
+
+```
+ api:
+ environment:
+ MEMPOOL_BACKEND: "none"
+ CORE_RPC_HOST: "172.27.0.1"
+ CORE_RPC_PORT: "8332"
+ CORE_RPC_USERNAME: "customuser"
+ CORE_RPC_PASSWORD: "custompassword"
+```
+
+The IP address in the example above refers to Docker's default gateway IP address so that the container can hit the `bitcoind` instance running on the host machine. If your setup is different, update it accordingly.
+
+Now, run:
+
+```bash
+$ docker-compose up
+```
+
+Your Mempool instance should be running at http://localhost. The graphs will be populated as new transactions are detected.
+
+## `bitcoind` + Electrum Server Configuration
+
+First, configure `bitcoind` as specified above, and make sure your Electrum server is running and synced.
+
+Then, make sure the following variables are set in `docker-compose.yml`, as shown below, so Mempool can connect to your Electrum server:
+
+```
+ api:
+ environment:
+ MEMPOOL_BACKEND: "electrum"
+ ELECTRUM_HOST: "172.27.0.1"
+ ELECTRUM_PORT: "50002"
+ ELECTRUM_TLS_ENABLED: "false"
+```
+
+Of course, if your Docker host IP address is different, update accordingly.
+
+With `bitcoind` and Electrum Server set up, run Mempool with:
+
+```bash
+$ docker-compose up
+```
+
+## Further Configuration
+
+Optionally, you can override any other backend settings from `mempool-config.json`.
+
+Below we list all settings from `mempool-config.json` and the corresponding overrides you can make in the `api` > `environment` section of `docker-compose.yml`.
+
+
+
+`mempool-config.json`:
+```
+ "MEMPOOL": {
+ "NETWORK": "mainnet",
+ "BACKEND": "electrum",
+ "HTTP_PORT": 8999,
+ "SPAWN_CLUSTER_PROCS": 0,
+ "API_URL_PREFIX": "/api/v1/",
+ "POLL_RATE_MS": 2000,
+ "CACHE_DIR": "./cache",
+ "CLEAR_PROTECTION_MINUTES": 20,
+ "RECOMMENDED_FEE_PERCENTILE": 50,
+ "BLOCK_WEIGHT_UNITS": 4000000,
+ "INITIAL_BLOCKS_AMOUNT": 8,
+ "MEMPOOL_BLOCKS_AMOUNT": 8,
+ "PRICE_FEED_UPDATE_INTERVAL": 600,
+ "USE_SECOND_NODE_FOR_MINFEE": false,
+ "EXTERNAL_ASSETS": ["https://raw.githubusercontent.com/mempool/mining-pools/master/pools.json"],
+ "STDOUT_LOG_MIN_PRIORITY": "info"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ MEMPOOL_NETWORK: ""
+ MEMPOOL_BACKEND: ""
+ MEMPOOL_HTTP_PORT: ""
+ MEMPOOL_SPAWN_CLUSTER_PROCS: ""
+ MEMPOOL_API_URL_PREFIX: ""
+ MEMPOOL_POLL_RATE_MS: ""
+ MEMPOOL_CACHE_DIR: ""
+ MEMPOOL_CLEAR_PROTECTION_MINUTES: ""
+ MEMPOOL_RECOMMENDED_FEE_PERCENTILE: ""
+ MEMPOOL_BLOCK_WEIGHT_UNITS: ""
+ MEMPOOL_INITIAL_BLOCKS_AMOUNT: ""
+ MEMPOOL_MEMPOOL_BLOCKS_AMOUNT: ""
+ MEMPOOL_PRICE_FEED_UPDATE_INTERVAL: ""
+ MEMPOOL_USE_SECOND_NODE_FOR_MINFEE: ""
+ MEMPOOL_EXTERNAL_ASSETS: ""
+ MEMPOOL_STDOUT_LOG_MIN_PRIORITY: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+"CORE_RPC": {
+ "HOST": "127.0.0.1",
+ "PORT": 8332,
+ "USERNAME": "mempool",
+ "PASSWORD": "mempool"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ CORE_RPC_HOST: ""
+ CORE_RPC_PORT: ""
+ CORE_RPC_USERNAME: ""
+ CORE_RPC_PASSWORD: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "ELECTRUM": {
+ "HOST": "127.0.0.1",
+ "PORT": 50002,
+ "TLS_ENABLED": true
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ ELECTRUM_HOST: ""
+ ELECTRUM_PORT: ""
+ ELECTRUM_TLS: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "ESPLORA": {
+ "REST_API_URL": "http://127.0.0.1:3000"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ ESPLORA_REST_API_URL: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "SECOND_CORE_RPC": {
+ "HOST": "127.0.0.1",
+ "PORT": 8332,
+ "USERNAME": "mempool",
+ "PASSWORD": "mempool"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ SECOND_CORE_RPC_HOST: ""
+ SECOND_CORE_RPC_PORT: ""
+ SECOND_CORE_RPC_USERNAME: ""
+ SECOND_CORE_RPC_PASSWORD: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "DATABASE": {
+ "ENABLED": true,
+ "HOST": "127.0.0.1",
+ "PORT": 3306,
+ "DATABASE": "mempool",
+ "USERNAME": "mempool",
+ "PASSWORD": "mempool"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ DATABASE_ENABLED: ""
+ DATABASE_HOST: ""
+ DATABASE_PORT: ""
+ DATABASE_DATABASE: ""
+ DATABASE_USERAME: ""
+ DATABASE_PASSWORD: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "SYSLOG": {
+ "ENABLED": true,
+ "HOST": "127.0.0.1",
+ "PORT": 514,
+ "MIN_PRIORITY": "info",
+ "FACILITY": "local7"
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ SYSLOG_ENABLED: ""
+ SYSLOG_HOST: ""
+ SYSLOG_PORT: ""
+ SYSLOG_MIN_PRIORITY: ""
+ SYSLOG_FACILITY: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "STATISTICS": {
+ "ENABLED": true,
+ "TX_PER_SECOND_SAMPLE_PERIOD": 150
+ },
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ STATISTICS_ENABLED: ""
+ STATISTICS_TX_PER_SECOND_SAMPLE_PERIOD: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "BISQ": {
+ "ENABLED": false,
+ "DATA_PATH": "/bisq/statsnode-data/btc_mainnet/db"
+ }
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ BISQ_ENABLED: ""
+ BISQ_DATA_PATH: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "SOCKS5PROXY": {
+ "ENABLED": false,
+ "HOST": "127.0.0.1",
+ "PORT": "9050",
+ "USERNAME": "",
+ "PASSWORD": ""
+ }
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ SOCKS5PROXY_ENABLED: ""
+ SOCKS5PROXY_HOST: ""
+ SOCKS5PROXY_PORT: ""
+ SOCKS5PROXY_USERNAME: ""
+ SOCKS5PROXY_PASSWORD: ""
+ ...
+```
+
+
+
+`mempool-config.json`:
+```
+ "PRICE_DATA_SERVER": {
+ "TOR_URL": "http://wizpriceje6q5tdrxkyiazsgu7irquiqjy2dptezqhrtu7l2qelqktid.onion/getAllMarketPrices",
+ "CLEARNET_URL": "https://price.bisq.wiz.biz/getAllMarketPrices"
+ }
+```
+
+Corresponding `docker-compose.yml` overrides:
+```
+ api:
+ environment:
+ PRICE_DATA_SERVER_TOR_URL: ""
+ PRICE_DATA_SERVER_CLEARNET_URL: ""
+ ...
+```