Add docker compose for one step setup with testnet

Dockerfile

@@ -21,4 +21,9 @@ FROM base as result
 # Copy the binaries
 COPY --from=electrs-build /root/.cargo/bin/electrs /usr/bin/electrs
 
-WORKDIR /
+WORKDIR /electrs
+
+# Copy config file
+COPY ./docker/testnet/conf.toml ./electrs.toml
+
+CMD ["/usr/bin/electrs", "--conf=/electrs/electrs.toml"]

README.md

@@ -16,7 +16,6 @@ allowing the user to keep real-time track of balances and transaction history us
 Since it runs on the user's own machine, there is no need for the wallet to communicate with external Electrum servers,
 thus preserving the privacy of the user's addresses and balances.
 
-
 ## Usage
 
 **Please prefer to use OUR usage guide!**
@@ -30,23 +29,24 @@ It's a bad idea to run it publicly as it'd expose you to DoS and maybe also othe
 If you want to run a public server you may be interested in the [Blockstream fork of electrs](https://github.com/Blockstream/electrs)
 which is better optimized for public usage at the cost of consuming *significantly* more resources.
 
- * [Installation from source](doc/install.md)
- * [Pre-built binaries](doc/binaries.md) (No official binaries available but a beta repository is available for installation)
- * [Configuration](doc/config.md)
- * [Usage](doc/usage.md)
- * [Monitoring](doc/monitoring.md)
- * [Upgrading](doc/upgrading.md) - **contains information about important changes from older versions**
+- [Installation from source](doc/install.md)
+- [Pre-built binaries](doc/binaries.md) (No official binaries available but a beta repository is available for installation)
+- [Configuration](doc/config.md)
+- [Usage](doc/usage.md)
+- [Monitoring](doc/monitoring.md)
+- [Upgrading](doc/upgrading.md) - **contains information about important changes from older versions**
+- [Docker](doc/docker.md)
 
 ## Features
 
- * Supports Electrum protocol [v1.4](https://electrumx-spesmilo.readthedocs.io/en/latest/protocol.html)
- * Maintains an index over transaction inputs and outputs, allowing fast balance queries
- * Fast synchronization of the Bitcoin blockchain (~6.5 hours for ~504GB @ August 2023) using HDD storage.
- * Low index storage overhead (~10%), relying on a local full node for transaction retrieval
- * Efficient mempool tracker (allowing better fee [estimation](https://github.com/spesmilo/electrum/blob/59c1d03f018026ac301c4e74facfc64da8ae4708/RELEASE-NOTES#L34-L46))
- * Low CPU & memory usage (after initial indexing)
- * [`txindex`](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch03.asciidoc#txindex) is not required for the Bitcoin node
- * Uses a single [RocksDB](https://github.com/spacejam/rust-rocksdb) database, for better consistency and crash recovery
+- Supports Electrum protocol [v1.4](https://electrumx-spesmilo.readthedocs.io/en/latest/protocol.html)
+- Maintains an index over transaction inputs and outputs, allowing fast balance queries
+- Fast synchronization of the Bitcoin blockchain (~6.5 hours for ~504GB @ August 2023) using HDD storage.
+- Low index storage overhead (~10%), relying on a local full node for transaction retrieval
+- Efficient mempool tracker (allowing better fee [estimation](https://github.com/spesmilo/electrum/blob/59c1d03f018026ac301c4e74facfc64da8ae4708/RELEASE-NOTES#L34-L46))
+- Low CPU & memory usage (after initial indexing)
+- [`txindex`](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch03.asciidoc#txindex) is not required for the Bitcoin node
+- Uses a single [RocksDB](https://github.com/spacejam/rust-rocksdb) database, for better consistency and crash recovery
 
 ## Altcoins
 

doc/docker.md

@@ -0,0 +1,70 @@
+# Docker installation
+
+## Docker-based installation from source
+
+**Important**: The `Dockerfile` is provided for demonstration purposes and may
+NOT be suitable for production use. The maintainers of electrs are not deeply
+familiar with Docker, so you should DYOR. If you are not familiar with Docker
+either it's probably be safer to NOT use it.
+
+Note: currently Docker installation links statically
+
+Note: health check only works if Prometheus is running on port 4224 inside
+container
+
+```bash
+$ docker build -t electrs-app .
+$ mkdir db
+$ docker run --network host \
+             --volume $HOME/.bitcoin:/home/user/.bitcoin:ro \
+             --volume $PWD/db:/home/user/db \
+             --env ELECTRS_DB_DIR=/home/user/db \
+             --rm -i -t electrs-app
+```
+
+If not using the host-network, you probably want to expose the ports for electrs
+and Prometheus like so:
+
+```bash
+$ docker run --volume $HOME/.bitcoin:/home/user/.bitcoin:ro \
+             --volume $PWD/db:/home/user/db \
+             --env ELECTRS_DB_DIR=/home/user/db \
+             --env ELECTRS_ELECTRUM_RPC_ADDR=0.0.0.0:50001 \
+             --env ELECTRS_MONITORING_ADDR=0.0.0.0:4224 \
+             --rm -i -t electrs-app
+```
+
+To access the server from outside Docker, add `-p 50001:50001 -p 4224:4224` but
+be aware of the security risks. Good practice is to group containers that needs
+access to the server inside the same Docker network and not expose the ports to
+the outside world.
+
+## Docker compose, one step for installation
+
+**NOTE**: This is intend for one step setup with testnet/signet/regnet, inspired
+by [Polar](https://github.com/jamaljsr/polar). **NOT RECOMMAND WITH MAINNET**
+
+To setup testnet, just switch to the [docker](../docker/testnet), and then run:
+
+```bash
+docker compose up -d
+```
+
+If you are not using Docker Desktop, run:
+
+```bash
+docker-compose up -d
+```
+
+The default rpc auth info for bitcoin core is: `alice:alice`, if you want to
+change it, just create a new one with [rpcauth.py](https://github.com/bitcoin/bitcoin/tree/master/share/rpcauth)
+and replace both line 19 in `docker-compose.yml` and line 16 in `electrs.toml`
+with new generated auth info:
+
+```
+-rpcauth=alice:128f22494cc2208ea8376a3d0b45a131$9cc0187c0e49f35454a3ed1250e40ecaef420cfcd294d3ac22496adbe64f04b9
+```
+
+Using it with bitcoin mainnet highly not recommand, use it with you own risk.
+It can not start properly with mainnet by default, you need to generated new rpc
+auth info and modify `docker-compose.yml` and `electrs.toml`.

doc/install.md

@@ -5,8 +5,8 @@
 
 ```bash
 $ sudo apt update
-$ sudo apt install -y clang cmake build-essential git cargo 
-$ git clone https://github.com/romanz/electrs 
+$ sudo apt install -y clang cmake build-essential git cargo
+$ git clone https://github.com/romanz/electrs
 $ cd electrs
 $ cargo build --locked --release
 $ ./target/release/electrs --version  # should print the latest version
@@ -231,36 +231,3 @@ It's a bit long but sufficient! You will find the resulting binary in `target/aa
 #### Generating man pages
 
 If you installed `cfg_me` to generate man page, you can run `cfg_me man` to see it right away or `cfg_me -o electrs.1 man` to save it into a file (`electrs.1`).
-
-## Docker-based installation from source
-
-**Important**: The `Dockerfile` is provided for demonstration purposes and may NOT be suitable for production use.
-The maintainers of electrs are not deeply familiar with Docker, so you should DYOR.
-If you are not familiar with Docker either it's probably be safer to NOT use it.
-
-Note: currently Docker installation links statically
-
-Note: health check only works if Prometheus is running on port 4224 inside container
-
-```bash
-$ docker build -t electrs-app .
-$ mkdir db
-$ docker run --network host \
-             --volume $HOME/.bitcoin:/home/user/.bitcoin:ro \
-             --volume $PWD/db:/home/user/db \
-             --env ELECTRS_DB_DIR=/home/user/db \
-             --rm -i -t electrs-app
-```
-
-If not using the host-network, you probably want to expose the ports for electrs and Prometheus like so:
-
-```bash
-$ docker run --volume $HOME/.bitcoin:/home/user/.bitcoin:ro \
-             --volume $PWD/db:/home/user/db \
-             --env ELECTRS_DB_DIR=/home/user/db \
-             --env ELECTRS_ELECTRUM_RPC_ADDR=0.0.0.0:50001 \
-             --env ELECTRS_MONITORING_ADDR=0.0.0.0:4224 \
-             --rm -i -t electrs-app
-```
-
-To access the server from outside Docker, add `-p 50001:50001 -p 4224:4224` but be aware of the security risks. Good practice is to group containers that needs access to the server inside the same Docker network and not expose the ports to the outside world.

docker/bitcoin/conf.toml

@@ -0,0 +1,34 @@
+# Which chain you want to use.
+# Allowed values: 'bitcoin', 'testnet', 'regtest' or 'signet'
+network = "bitcoin"
+
+# The listening RPC address of bitcoind,
+# json-rpc-ports:
+#   bitcoin: 8332
+#   testnet: 18332
+#   signnet: 38332
+#   regtest: 18443
+daemon_rpc_addr = "bitcoind:8332"
+
+# Using cookie file to auth
+#cookie_file = "~/.bitcoin/.cookie"
+# Using rpc auth instead of cookie file
+auth = "<rpcauth-username>:<rpcauth-password>"
+
+# The listening P2P address of bitcoind
+# p2p-ports:
+#   bitcoin: 8333
+#   testnet: 18333
+#   signnet: 38333
+#   regtest: 18444
+daemon_p2p_addr = "bitcoind:8333"
+
+# Directory where the index should be stored. It should have at least 70GB of free space.
+db_dir = "/electrs/db"
+
+# The address on which electrs should listen. Warning: 0.0.0.0 is probably a bad idea!
+# Tunneling is the recommended way to access electrs remotely.
+electrum_rpc_addr = "127.0.0.1:50001"
+
+# How much information about internal workings should electrs print. Increase before reporting a bug.
+log_filters = "INFO"

docker/bitcoin/docker-compose.yml

@@ -0,0 +1,44 @@
+version: "3"
+services:
+  bitcoind:
+    container_name: bitcoind
+    privileged: true
+    image: oneforalonee/bitcoind:v26.0
+    restart: on-failure
+    hostname: bitcoind
+    stop_grace_period: 5m
+    environment:
+      USERID: ${USERID:-1000}
+      GROUPID: ${GROUPID:-1000}
+    command: >-
+      bitcoind -server=1 -chain=main
+      -debug=1 -zmqpubrawblock=tcp://0.0.0.0:28332
+      -zmqpubrawtx=tcp://0.0.0.0:28333 -zmqpubhashblock=tcp://0.0.0.0:28334
+      -txindex=1 -dnsseed=0 -upnp=0 -rpcbind=0.0.0.0 -rpcallowip=0.0.0.0/0
+      -rpcport=8332 -rest -listen=1 -listenonion=0
+    expose:
+      - 8332
+    ports:
+      - 8332:8332
+    volumes:
+      - ./bitcoind:/home/bitcoin/.bitcoin
+
+  electrs:
+    depends_on:
+      - bitcoind
+    links:
+      - bitcoind
+    container_name: electrs
+    privileged: true
+    image: oneforalonee/electrs:latest
+    restart: on-failure
+    hostname: electrs
+    command: >-
+      /usr/bin/electrs --conf=/electrs/electrs.toml
+    expose:
+      - 50001
+    ports:
+      - 50001:50001
+    volumes:
+      - ./electrs_db:/electrs/db
+      - ./conf.toml:/electrs/electrs.toml

docker/testnet/conf.toml

@@ -0,0 +1,34 @@
+# Which chain you want to use.
+# Allowed values: 'bitcoin', 'testnet', 'regtest' or 'signet'
+network = "testnet"
+
+# The listening RPC address of bitcoind,
+# json-rpc-ports:
+#   bitcoin: 8332
+#   testnet: 18332
+#   signnet: 38332
+#   regtest: 18443
+daemon_rpc_addr = "bitcoind:18332"
+
+# Using cookie file to auth
+#cookie_file = "~/.bitcoin/.cookie"
+# Using rpc auth instead of cookie file
+auth = "alice:alice"
+
+# The listening P2P address of bitcoind
+# p2p-ports:
+#   bitcoin: 8333
+#   testnet: 18333
+#   signnet: 38333
+#   regtest: 18444
+daemon_p2p_addr = "bitcoind:18333"
+
+# Directory where the index should be stored. It should have at least 70GB of free space.
+db_dir = "/electrs/db"
+
+# The address on which electrs should listen. Warning: 0.0.0.0 is probably a bad idea!
+# Tunneling is the recommended way to access electrs remotely.
+electrum_rpc_addr = "0.0.0.0:50002"
+
+# How much information about internal workings should electrs print. Increase before reporting a bug.
+log_filters = "INFO"

docker/testnet/docker-compose.yml

@@ -0,0 +1,45 @@
+version: "3"
+services:
+  bitcoind:
+    container_name: bitcoind
+    privileged: true
+    image: oneforalonee/bitcoind:v26.0
+    restart: on-failure
+    hostname: bitcoind
+    stop_grace_period: 5m
+    environment:
+      USERID: ${USERID:-1000}
+      GROUPID: ${GROUPID:-1000}
+    command: >-
+      bitcoind -server=1 -testnet=1
+      -zmqpubrawblock=tcp://0.0.0.0:28334
+      -zmqpubrawtx=tcp://0.0.0.0:28335 -zmqpubhashblock=tcp://0.0.0.0:28336
+      -txindex=1 -rpcbind=0.0.0.0 -rpcallowip=0.0.0.0/0
+      -rpcport=18332 -rest -listen=1 -listenonion=0
+      -rpcauth=alice:128f22494cc2208ea8376a3d0b45a131$9cc0187c0e49f35454a3ed1250e40ecaef420cfcd294d3ac22496adbe64f04b9
+    expose:
+      - 18332
+    ports:
+      - 18332:18332
+    volumes:
+      - ./bitcoind:/home/bitcoin/.bitcoin
+
+  electrs:
+    depends_on:
+      - bitcoind
+    links:
+      - bitcoind
+    container_name: electrs
+    privileged: true
+    image: oneforalonee/electrs:latest
+    restart: on-failure
+    hostname: electrs
+    command: >-
+      /usr/bin/electrs --conf=/electrs/electrs.toml
+    expose:
+      - 50002
+    ports:
+      - 50002:50002
+    volumes:
+      - ./db:/electrs/db
+      - ./conf.toml:/electrs/electrs.toml