coreos-bitcoind

coreos-bitcoind is an automatically built Docker image for bitcoind.

It can be used as a standalone container or as a CoreOS service.

The image is based on Alpine Linux resulting in a smallish image of only 46 MB (the smallest such image to my knowledge).

Table of Contents

• Standalone usage
  • Configuration
  • Data persistence
• CoreOS usage
  • Configuration
  • Data persistence
  • Data persistence using AWS EBS volume

Standalone usage

docker run \
  -d \
  --name=bitcoind \
  -p 8333:8333 \
  -p 8332:8332 \
  olalond3/coreos-bitcoind

# view debug.log logs in real time
docker logs --follow bitcoind

Or with docker-compose (the docker-compose.yml must be present in your current directory):

docker-compose up

For playing with bitcoind inside an ephemeral container:

docker run --rm -it olalond3/coreos-bitcoind /bin/bash
bash-4.3# bitcoind --help

Or with docker-compose:

docker-compose run bitcoind /bin/bash

To use bitcoin-cli on a running bitcoind container, use the following command:

docker exec -it <container name> bitcoin-cli -conf=/etc/bitcoind.conf <command>

For example, to get a new deposit address:

docker exec -it bitcoind bitcoin-cli -conf=/etc/bitcoin.conf getnewaddress

For more commands, see the Bitcoin Developer Reference.

Configuration

The container is entirely configurable through environment variables that follow this pattern BITCOIN_CONF_ARG=value, where ARG is one of the bitcoind configuration flags.

See docker run --rm -t olalond3/coreos-bitcoind bitcoind --help for a list.

The following example starts bitcoind in testnet mode with rpc enabled (if the rpcuser and/or rpcpassword are not specified, they will be generated automatically):

docker run \
  -d \
  --name=bitcoind \
  -p 18333:18333 \
  -p 18332:18332 \
  -e BITCOIN_CONF_SERVER=1 \
  -e BITCOIN_CONF_TESTNET=1 \
  -e BITCOIN_CONF_RPCUSER=someuser \
  olalond3/coreos-bitcoind

# view automatically generated rpcpassword or user
docker logs bitcoind | grep ^rpc

Data persistence

Data can be persisted through a data container:

docker run --name=bitcoind-data -v /bitcoin alpine:3.2 true
docker run \
  --volumes-from=bitcoind-data \
  -d \
  --name=bitcoind \
  -p 8333:8333 \
  -p 8332:8332 \
  olalond3/coreos-bitcoind

Or by mounting a directory from the host:

docker run \
  -v ~/.bitcoin:/bitcoin
  -d \
  --name=bitcoind \
  -p 8333:8333 \
  -p 8332:8332 \
  olalond3/coreos-bitcoind

Inside the container, the data folder is /bitcoin/ and the configuration file is /etc/bitcoind.conf.

CoreOS usage

Note: remove or modify the MachineMetadata directive from bitcoind@.service if it doesn't apply to you.

fleetctl start bitcoind@<instance>

For example:

fleetctl start bitcoind@livenet

Additional bitcoind services can be launched by choosing a different name following the @ (referred to as instance name).

bitcoind@testnet is handled specially by automatically defaulting to testnet=1 in the configuration.

The service opens ports on the host, so when running multiple instances on a same host, you must ensure that ports (e.g. rpcport and port do not conflict).

Configuration

Configuration is entirely done through etcd. Internally, confd is used for automatically restarting bitcoind when etcd configuration values change.

The configuration directory for a given service is /bitcoin/<instance>/conf where <instance> is the instance name used when launching the service (e.g. bitcoind@livenet's directory would be /bitcoin/livenet/conf.

All bitcoind configuration keys are supported.

See docker run --rm -t olalond3/coreos-bitcoind bitcoind --help for a list.

Example:

etcdctl set /bitcoin/livenet/conf/rpcuser someuser
etcdctl set /bitcoin/livenet/conf/rpcpassword somepassword

If the rcpuser and rpcpassword keys are not set at first launch, the service will generate some automatically. To see those values, use the follow commands:

etcdctl get /bitcoin/livenet/conf/rpcuser
etcdctl get /bitcoin/livenet/conf/rpcpassword

Data persistence

By default, the bitcoind service will mount the /data/bitcoin/<instance> directory from the host if it exists and use it as its data directory. If the directory does not exist, at every restart, bitcoind will lose its wallet and need to download the whole blockchain from scratch.

Data persistence using AWS EBS volume

If you are running your CoreOS cluster on AWS, you can use the bitcoind-ebs@ service which will attach an EBS volume on the host and mount it at /data/bitcoin/<instance>.

The EBS volume must be created and formatted manually. It must be in the same AWS region as the EC2 machine the service is scheduled on (todo: automate this or replace with flocker).

Create a new 70+ GB SSD EBS volume in AWS EC2 web interface. Attach the volume to a temporary Linux EC2 and format the disk with mkfs:

mkfs -t ext4 /dev/xvdg

Set the following configuration keys:

etcdctl set /aws/key <aws key id>
etcdctl set /aws/secret <aws key secret>
etcdctl set /aws/region <aws region of ebs volume>
etcdctl set /bitcoin/<instance>/ebs/volume_id <ebs volume id>

The aws key must have the permission to perform the following actions:

• aws ec2 describe-volumes
• aws ec2 attach-volume
• aws ec2 detach-volume

/aws/region must be a region name (e.g. us-east-1), not an availability zone (e.g. us-east-1a).

Submit and load both units:

fleetctl load bitcoind@livenet bitcoind-ebs@livenet

Start bitcoind (this will automatically start bitcoind-ebs):

fleetctl start bitcoind@livenet

To restart the service, only stop and start bitcoind@livenet, bitcoind-ebs will stop/start by itself. For example:

fleetctl stop bitcoind@livenet
fleetctl start bitcoind@livenet