jamesob / docker-bitcoind

A configurable docker image for bitcoind

docker-bitcoind

A Docker configuration with sane defaults for running a fully-validating Bitcoin node. Binaries are retrieved from bitcoincore.org and verified for integrity based on the process described here.

Optional building from arbitrary git objects is possible (and pretty convenient).

Warning: don't trust the Docker registry

References on the Docker registry (https://hub.docker.com) are mutable. A malicious actor could change any images hosted there without you realizing it.

If you use an image served by the Docker registry, ensure that you retrieve it by its content hash, as detailed here. Or just build these images yourself.

With most software this doesn't matter too much, but running an authentic copy of Bitcoin Core is really important!

Warning: don't trust Docker

Consider whether your use of Bitcoin requires Docker. When you use a container runtime, you are using a lot of additional code written by other people, e.g. runc, docker, potentially docker-compose, potentially podman.

Is it necessary to rely on these dependencies? More code running underneath bitcoind is more chance for someone to meddle with the operation of your node.

Warning: don't rely on Dockerfile particulars

This repo may change Dockerfile implementation. Although the container interface itself (i.e. volume mounts, operational behavior) will remain stable, the implementation of how that happens is subject to change.

If your use relies on the particulars of, for example, the retrieval script (get-bitcoin.sh), please pin your usage of this repo to a particular git hash.

Tags available

• 0.13.0
• 0.13.1
• 0.13.2
• 0.14.3
• 0.15.2
• 0.16.3
• 0.17.0
• 0.17.0.1
• 0.17.1
• 0.17.2
• 0.18.0
• 0.18.1
• 0.19.0
• 0.19.1
• 0.20.0
• 0.20.1
• 0.21.0
• 0.21.1
• 0.21.2
• 22.0
• 23.0

As well as various git refs.

Labels available

Each image is built with certain labels:

• bitcoin_source: "release" or "git", depending on how the binaries were built
• bitcoin_version: if source=release, the release version (e.g. 23.0), if source=git "git:"
• git_ref: if source=git, the tag or branch used to build the image
• git_sha: if source=git, the specific git commit hash
• git_repo_url: if source=git, the repo used to build

Labels can be shown by running something like

% docker image inspect jamesob/bitcoind:master | jq '.[0] .Config .Labels'

{
  "bitcoin-configure-args": "--enable-reduce-exports --disable-bench --disable-gui-tests --disable-fuzz-binary --disable-ccache --disable-maintainer-mode --disable-dependency-tracking CFLAGS='-O2 -g'",
  "bitcoin-source": "git",
  "bitcoin-version": "git:master",
  "git-ref": "master",
  "git-repo-url": "https://github.com/bitcoin/bitcoin",
  "git-sha": "551c8e9526d2502f857e1ef6348c7f1380f37443"
}

Quick start

Requires that Docker be installed on the host machine.

Autogenerating a config

# Create some directory where your bitcoin data will be stored.
$ mkdir /home/youruser/bitcoin_data

$ $EDITOR envfile
BTC_RPCPASSWORD=your_password

$ docker run --name bitcoind -d \
   -e 'BTC_RPCUSER=foo' \
   -e 'BTC_TXINDEX=1' \
   --env-file envfile \
   -v /home/youruser/bitcoin_data:/bitcoin/data \
   -p 127.0.0.1:8332:8332 \
   -p 8333:8333 \
   jamesob/bitcoind:0.20.1

$ docker logs -f bitcoind
[ ... ]

Warning: if you specify your RPC password without using an envfile, it may be captured in your shell history. Use an envfile if you are going to use BTC_RPCPASSWORD.

If you want the RPC port to be accessible to remote hosts, remove the 127.0.0.1 from the -p ...8332 line and set BTC_RPCBIND=0.0.0.0.

Using your own config/datadir

If you want to use a preexisting data directory and your own config file, run

$ docker run --name jamesob/bitcoind:0.20.1 -d \
   -v /home/youruser/bitcoin_data:/bitcoin/data \
   -v /home/youruser/bitcoin.conf:/bitcoin/bitcoin.conf \
   -p 127.0.0.1:8332:8332 \
   -p 8333:8333 \
   jamesob/bitcoind:0.20.1

Building yourself

By default, the container runs under UID,GID=1000 to avoid executing as a privileged user. If you want to rebuild the container with different settings, you can do so:

$ git clone https://github.com/jamesob/docker-bitcoind
$ cd docker-bitcoind
$ docker build -t $YOUR_USER/bitcoind:$SOME_VERSION \
   --build-arg UID=$(id -u) \
   --build-arg GID=$(id -g) \
   --build-arg VERSION=$SOME_VERSION \
   --build-arg SOURCE=release \
   .

To build an arbitrary git object:

$ ./bin/build-docker-bitcoin master
$ ./bin/build-docker-bitcoin v24.0rc2
$ ./bin/build-docker-bitcoin <some git object>

Possible volume mounts

Path	Description
/bitcoin/data	Bitcoin's data directory
/bitcoin/bitcoin.conf	Bitcoin's configuration file

Configuration

A custom bitcoin.conf file can be placed at /bitcoin.conf. Otherwise, a default will be automatically generated based on environment variables passed to the container:

name	default
BTC_RPCUSER	btc
BTC_RPCPASSWORD
BTC_RPCPORT	8332
BTC_RPCBIND	127.0.0.1
BTC_RPCALLOWIP	::/0
BTC_RPCCLIENTTIMEOUT	30
BTC_DISABLEWALLET	1
BTC_TXINDEX	0
BTC_TESTNET	0
BTC_DBCACHE	0
BTC_ZMQPUBHASHTX	tcp://0.0.0.0:28333
BTC_ZMQPUBHASHBLOCK	tcp://0.0.0.0:28333
BTC_ZMQPUBRAWTX	tcp://0.0.0.0:28333
BTC_ZMQPUBRAWBLOCK	tcp://0.0.0.0:28333

Daemonizing

The smart thing to do if you're daemonizing is to use Docker's builtin restart policies (i.e. docker run --restart unless-stopped ...), but if you're insistent on using systemd, you could do something like

$ cat /etc/systemd/system/bitcoind.service

# bitcoind.service #######################################################################
[Unit]
Description=Bitcoind
After=docker.service
Requires=docker.service

[Service]
ExecStartPre=-/usr/bin/docker kill bitcoind
ExecStartPre=-/usr/bin/docker rm bitcoind
ExecStartPre=/usr/bin/docker pull jamesob/bitcoind
ExecStart=/usr/bin/docker run \
    --name bitcoind \
    -p 8333:8333 \
    -p 127.0.0.1:8332:8332 \
    -v /data/bitcoind:/root/.bitcoin \
    jamesob/bitcoind
ExecStop=/usr/bin/docker stop bitcoind

to ensure that bitcoind continues to run.

docker-bitcoind's Issues

World-readable bitcoin.conf

As per the title. This leaks RPC credentials.

Add a chmod 600 "${BITCOIN_CONF}" right after this line:

docker-bitcoind/bin/docker_entrypoint.sh

Line 60 in 1e04638

EOF

Diskfull message when downloading blockchain

I get a disk full error, but my disk is around 250Gb. It's a brand new laptop with only on big partition.

2018-02-22 23:08:38 Pre-allocating up to position 0xb00000 in rev00404.dat
2018-02-22 23:08:38 UpdateTip: new best=000000000000000005257f546f53d5fc6c80ed1046983d7d42905be647802f5d height=390486 version=0x00000004 log2_work=83.810245 tx=100397233 date='2015-12-27 14:32:05' progress=0.336760 cache=336.3MiB(2199420txo)
2018-02-22 23:08:38 UpdateTip: new best=000000000000000005873453485af6c31df6f9105912db8d621895715932addc height=390487 version=0x00000004 log2_work=83.810279 tx=100398187 date='2015-12-27 14:39:31' progress=0.336763 cache=336.0MiB(2196630txo)
2018-02-22 23:08:39 *** Disk space is low!
2018-02-22 23:08:39 Error: Error: Disk space is low!
2018-02-22 23:08:39 ERROR: AcceptBlock(): FindBlockPos failed
2018-02-22 23:08:39 ERROR: ProcessNewBlock: AcceptBlock FAILED
Error: Error: Disk space is low!
2018-02-22 23:08:39 tor: Thread interrupt
2018-02-22 23:08:39 scheduler thread interrupt
2018-02-22 23:08:39 addcon thread exit
2018-02-22 23:08:39 opencon thread exit
2018-02-22 23:08:39 Shutdown: In progress...
2018-02-22 23:08:39 torcontrol thread exit
2018-02-22 23:08:39 msghand thread exit
2018-02-22 23:08:39 net thread exit
2018-02-22 23:08:39 Dumped mempool: 6e-06s to copy, 0.001795s to dump
Error: Error: Disk space is low!
2018-02-22 23:08:39 *** Disk space is low!
2018-02-22 23:08:39 Error: Error: Disk space is low!
2018-02-22 23:08:39 *** Disk space is low!
2018-02-22 23:08:39 Error: Error: Disk space is low!
Error: Error: Disk space is low!
2018-02-22 23:08:41 Shutdown: done

Error: Cannot write to data directory '/bitcoin/data'; check permissions.

0.20.1

docker run --name bitcoind -d --restart=always  --env 'BTC_RPCUSER=____'  --env 'BTC_RPCPASSWORD=____'  --env 'BTC_TXINDEX=1'  --volume /home/bitcoin:/bitcoin/data --log-opt max-
size=1m --log-opt max-file=5 -p 8332:8332  --publish 8333:8333  jamesob/bitcoind

Missing bin/append-to-hosts.sh

# Workaround to address https://github.com/jamesob/docker-bitcoind/pull/16 while
# still not running as root user.
COPY ./bin/append-to-hosts.sh /usr/bin/append-to-hosts
RUN chmod +x /usr/bin/append-to-hosts

This file is absent from the repository, causing docker build to give up at that point.

New URL for sgerrand's signing key for alpine-pkg-glibc

sgerrand/alpine-pkg-glibc@6dffcfc

change to this:

&& wget -q -O /etc/apk/keys/sgerrand.rsa.pub https://alpine-pkgs.sgerrand.com/sgerrand.rsa.pub

how to start bitcoind with arguments

I stop the container and then bitcoin-core let me to use -reindex to build UTXOs. But I can't.
I'm a newbie to Docker.

Thank you very much.

use restart-policy in docker-run to eliminate upstart

why don't you use --restart unless-stopped in docker-run? Then no start scripts are necessary

RPC port 8332 should be localhost only

I know very little about docker, so please forgive me if I'm confused. The README suggests starting with the following parameter:

-p 8332:8332 \

This Docker manual says that will bind bitcoind's RPC port to the host systems port 8332 listening on all interfaces. Since RPC is unencrypted by default (even the authentication), it would probably be better to bind to just localhost. The above page suggests that could be done with:

-p 127.0.0.1:8332:8332

Note, this issue with Docker was first described here: https://twitter.com/LaurentMT/status/1067796761161490432

Could we make this Bitcoin Classic by default?

Hi, not to make this political but could this repository be Bitcoin Classic by default? I can create a branch with a pull request if it'dmake things easier for you. Thank you.

Backlink from docker hub page

Assuming that https://hub.docker.com/r/jamesob/bitcoind corresponds to this repo, the page could backlink to the source on GitHub?

Version bump to 22

Needs version bump, thx