From 3c3f3eab063ceb337678bfb011b5b4165665ac01 Mon Sep 17 00:00:00 2001 From: milah-247 <198606151+milah-247@users.noreply.github.com> Date: Mon, 12 Oct 2026 12:27:29 +0100 Subject: [PATCH] docs: explain initial electrs indexing and compaction behavior Document what to expect during the initial Bitcoin mainnet sync: the multi-day indexing and compaction phase, electrs sitting in D state with no new log lines, storage recommendations, how to get progress output (DEBUG=verbose / ELECTRS_ARGS=-vvvv), and using a longer Docker stop timeout so the container can shut electrs and bitcoind down cleanly. Also document the ELECTRS_ARGS passthrough. Closes #600 Co-Authored-By: milah-247 <198606151+milah-247@users.noreply.github.com> --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index e9f2a020..da742fb6 100644 --- a/README.md +++ b/README.md @@ -294,6 +294,43 @@ Set `-e ENABLE_LIGHTMODE=1` to enable [esplora-electrs's light mode](https://git Set `-e ONION_URL=http://xyz.onion` to enable the `Onion-Location` header. +Set `-e ELECTRS_ARGS="..."` to pass additional command-line arguments to esplora-electrs +(appended to the arguments generated by `run.sh`). + +## Initial sync and indexing + +Indexing Bitcoin mainnet from scratch is slow and disk-bound. After bitcoind has +fully synced, electrs reads every block and writes its index, then runs a full +RocksDB compaction. On Bitcoin mainnet this can take several days, even on +high-spec hardware (the database grows to over 1TB, or less with `ENABLE_LIGHTMODE=1`). + +What to expect while this is happening: + +- The `electrs` process may sit in the `D` (uninterruptible sleep) state with + near 0% CPU and high disk utilization for long periods. This is normal during + compaction and does not mean the process is hung. +- The last line in `/data/logs/electrs/current` may not change for hours or days + while compaction runs. There is no percentage-complete indicator. +- The HTTP API and Electrum server only become available once the initial + indexing and compaction have finished. + +Recommendations: + +- Use fast local NVMe storage, or provisioned-IOPS network storage (for example AWS + `io2` rather than `gp3`). Disk latency and random-read IOPS matter far more than + CPU count. Leave ample headroom: plan for at least ~2TB of free space for + bitcoind plus the electrs database on mainnet. +- To get more progress feedback, set `-e DEBUG=verbose` (which passes `-vvvv` to + electrs) or `-e ELECTRS_ARGS=-vvvv`. Trace output is logged as blocks are indexed. + You can also watch the size of `/data/electrs_bitcoin_db/` grow and use + `iostat -x` to confirm the disk is busy. +- Avoid restarting the container while the initial indexing is in progress. + When you do need to stop it, give it time to shut down cleanly: the container + waits up to 60 seconds for electrs and up to 300 seconds for bitcoind, but + Docker's default stop timeout is only 10 seconds. Use `docker stop -t 600 `, + or set `stop_grace_period: 10m` in Docker Compose, so the databases are not + killed mid-write. + ## Pull tor directly from Docker Hub - `blockstream/tor:latest` Run: `docker -d --name hidden_service blockstream/tor:latest tor -f /home/tor/torrc` (could add a `-v /extra/torrc:/home/tor/torrc`, if you have a custom torrc)