Skip to content

docs: explain initial electrs indexing and compaction behavior #692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
milah-247 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: explain initial electrs indexing and compaction behavior #692

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <container>`,
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)
Expand Down