Skip to content

Bitcoind

Images

I evaluated a number of images to use for bitcoind:

1. kylemanna

Discarded:

  • Does not seem to be actively maintained (only a dozen commmits in 2024)
  • Based on ubuntu: Dockerfile

2. Blockstream

3. bitcoin/bitcoin

Pros:

  • Light: uses debian:bookworm-slim (or alpine) as base and multistage build
  • Frequently updated

4. getumbrel

Issues:

  • There is no way to know whether the dockerhub images were built with github's Dockerfile

Authentication

We have three options for authenticating other services

rpcuser and rpcpassword

in the command section of docker, we can specify

  -rpcuser="${BITCOIN_RPC_USER}"
  -rpcpassword="${BITCOIN_RPC_PASS}"

However, this has several problems:

  1. Security: The password is visible on the host: 

    ps -ef | grep rpcpassword
101000    479430  479409  2 Jan11 ?        00:14:55 bitcoind -port=8333 -rpcport=8332 -rpcbind=127.0.0.1 -rpcbind=10.21.24.8 -rpcallowip=127.0.0.1 -rpcallowip=10.21.24.0/24 -rpcuser=umbrel -rpcpassword=visible_password  -rpccookiefile=/data/.bitcoin/.cookie -rpcauth="umbrel:hashed-password" -zmqpubrawblock=tcp://0.0.0.0:28332 -zmqpubrawtx=tcp://0.0.0.0:28333 -zmqpubhashblock=tcp://0.0.0.0:28334 -zmqpubsequence=tcp://0.0.0.0:28335 -deprecatedrpc=warnings

  2. Missing .bitcoin/.cookie file: When you specify rpcuser and rpcpassword this file is elminated (even if you add command option -rpccookiefile). Services, such as Bitcoin RPC Explorer, which cannot use rpcuser/rpcpassword

  3. Deprecation: bitcoin core is deprecating rpcuser/rpcpassword in favor of rpcauth which has encoded password string

.bitcoin/.cookie

  1. Widely supported: Most apps can use this file to connect to bitcoind
  2. Security: No password exposed on command line and the file is dynamically generated on each restart: 
    __cookie__:60dd68f9386ec04d063acf13dc879abcb385ec2572b30a969163dc769dad78b6

rpcauth

Recommended way to connect as the password is encoded. However not all applications support it.

Algonode's apps authentication use

Algonode's apps are connecting with cookies, however the rpcauth is also configured.

Apps currently connecting to bitcoind:

  1. electrs currently uses .bitcoind/.cookie mounted as a volume
  2. btc-rpc-explorer also uses .bitcoind/.cookie mounted as volume

Reference: lukechilds' comment on use of .cookie

Prameters bitcoin.conf

umbrel stores parameter in bitcoin/umbrel-bitcoin.conf

core

Option Default (if any) Your Value Notes
dbcache 450 MiB 4096 ✅ Large bump – significantly increased
txindex 0 1 ✅ Indexing full transaction set
blockfilterindex 0 1 ✅ Enables all compact filters
maxmempool 300 300 ⚠️ Default is 300, so it's redundant
mempoolexpiry 336 (14 days) 336 ⚠️ Same as default in recent versions
persistmempool 1 1 ⚠️ Default = 1, redundant
maxorphantx 100 100 ⚠️ Default = 100

relay

Option Default Your Value Notes
datacarriersize 83 83 ✅ Confirmed default, but explicitly setting it is fine

network

Option Default Your Value Notes
onlynet=onion Not set ✅ ✅ Explicitly restricting to Tor
onion=10.21.22.2:9050 Not set ✅ ✅ Custom Tor proxy
torcontrol=10.21.22.2:9051 Not set ✅ ✅ Required for Tor control functionality
i2psam=10.21.23.2:7656 Not set ✅ ✅ I2P disabled by default
onlynet=i2p Not set ✅ ✅ Explicit I2P-only override
listen 1 1 ⚠️ Redundant, same as default
listenonion 1 0 ✅ Changed — disables listening via Tor
i2pacceptincoming 1 0 ✅ Changed — disables I2P inbound connections
whitelist=10.21.0.0/16 Not set ✅ ✅ Custom whitelist for local subnet
peerblockfilters 0 1 ✅ Needed for BIP 157 support
bantime 86400 86400 ⚠️ Same as default (1 day)
maxconnections 125 125 ⚠️ Default value — redundant unless changed
maxreceivebuffer 5000 5000 ✅ Increased from default (5000 is non-default)
maxsendbuffer 1000 1000 ✅ May differ slightly from default (1000 is high)
maxtimeadjustment 4200 4200 ⚠️ Matches default
peertimeout 60 60 ⚠️ Matches default
timeout 5000 (ms) 5000 ✅ Custom timeout (default varies per version)
maxuploadtarget 0 (unlimited) 50 ✅ Explicit bandwidth limit set

rpc

Option Default Your Value Notes
rpcworkqueue 16 (used to be 4) 128 ✅ Significantly increased from default

main

Option Default Your Value Notes
bind=0.0.0.0:8333 Bind to local only ✅ ✅ Allows external connections
bind=10.21.22.8:8334=onion Not set ✅ ✅ Required to advertise onion address