Running an epoch node on Docker
This document describes:
You must have docker installed on a host machine.
Docker image is automatically build and published on DockerHub. All tagged source code versions have their own docker image tag as well. Latest tagged ("stable") version is tagged with
Master branch of the source code is tagged as
To pull the latest "stable" image run:
docker pull aeternity/epoch
Please prepare node configuration.
The minimal configuration to join the testnet is the following (mind that
beneficiary must be changed to valid account public key, see configuration documentation for more details):
--- keys: peer_password: "top secret" dir: ./keys chain: persist: true mining: autostart: true beneficiary: "encoded_beneficiary_pubkey_to_be_replaced" cuckoo: miner: executable: lean29-generic extra_args: "" edge_bits: 29
Note that if you want to use the default miner, remove the
mining.cuckoo section and increase the docker container memory at least 4GB.
Generating beneficiary account for the first time
If you don't have your beneficiary account public key yet, but you have Docker image, you can use
keys_gen tool to generate public-private keypair from the inside of the Docker container.
/tmp/generated_keysis a directory on you local machine;
- you change
my_passwordin the command below to your password that will protect your public-private keypair,
docker run --entrypoint=/bin/bash \ -v /tmp/generated_keys:/home/epoch/node/generated_keys \ aeternity/epoch \ -c './bin/epoch keys_gen my_password'
Your generated keypair will be located in
/tmp/generated_keys on your machine, and your public key to be put in the configuration file will be printed in the console.
For more details see configuration documentation beneficiary section.
External Peer Address
Please note that, if your node is behind a firewall, you need to open and map the TCP port defined by (
port with default
3015) option in your firewall to the container port.
If the publicly available port has to be different from the internal port it as to be reflected in the configuration with the (
Docker image has packaged the addresses of testnet seed peers in the configuration. To change the peers configuration (e.g. join other network) change the configuration file.
Start a Node
Assuming configuration file location is
To start a docker node and join the testnet run:
docker run -d --name epoch_node0 -p 3013:3013 \ -v ~/.aeternity/myepoch.yaml:/home/epoch/myepoch.yaml \ -e EPOCH_CONFIG=/home/epoch/myepoch.yaml \ aeternity/epoch
Verify the node is running:
Arguments can also be passed to epoch node, for example to enable API debug endpoints:
docker run -d -p 3013:3013 \ -v ~/.aeternity/myepoch.yaml:/home/epoch/myepoch.yaml \ -e EPOCH_CONFIG=/home/epoch/myepoch.yaml \ aeternity/epoch -aehttp enable_debug_endpoints true
Stop a Node
To stop a docker node run:
docker stop epoch_node0
Execute command on a running node
To execute any command on a running node use:
docker exec epoch_node0 CMD
For example to check what's in the epoch logs run:
docker exec epoch_node0 tail log/epoch.log
To persist blockchain data and node keys between container runs, use Docker volumes. Replace
~/.aeternity/db with location of your choice.
docker run -d -p 3013:3013 \ -v ~/.aeternity/myepoch.yaml:/home/epoch/myepoch.yaml \ -e EPOCH_CONFIG=/home/epoch/myepoch.yaml \ --hostname node0 \ -v ~/.aeternity/db:/home/epoch/node/data/mnesia \ -v ~/.aeternity/keys:/home/epoch/node/keys \ aeternity/epoch
Note: make sure
hostname option is set when reusing the mnesia data directory
Small local network (not connected to testnet) can be created with
It runs three nodes using the
mean15-generic miner (fastest generic miner) and a proxy server to allow CORS.
All local network nodes have
ak_25eTK8PaiLpREqBkP3yDNWJAwXjWSR8tbn3zu8SXaNx824A1AJ set as node beneficiary (for more details on beneficiary see configuration documentation).
Public-private keypair of
ak_25eTK8PaiLpREqBkP3yDNWJAwXjWSR8tbn3zu8SXaNx824A1AJ beneficiary can be found here: as the private key is publicly available, this setup must not be connected on the live network.
Base58Check-encoded form of private key, which matches above beneficiary public key:
Both external and internal API are exposed to the docker host, the URL pattern is as follows:
- external API - http://$DOCKER_HOST_ADDRESS:$NODE_PORT/
- internal API - http://$DOCKER_HOST_ADDRESS:$NODE_PORT/internal
Websocket API is exposed to the docker host with following URL pattern:
- channels API - ws://$DOCKER_HOST_ADDRESS:$NODE_PORT/channel
node1- port 3001
node2- port 3002
node3- port 3003
For example to access
node2 peer public key, assuming docker host address is
To start the network:
docker-compose up -d
To destroy the network:
To cleanup the associated docker volumes,
-v option could be used:
docker-compose down -v
More details can be found in
Docker compose uses the
aeternity/epoch:latest image, it will be pulled from docker hub if it's not found locally.
To create a network with the source code in this repository, one should build a local image beforehand:
By default the localnet has set default mine rate of 1 block per 15 seconds.
It can be changed by setting
EPOCH_MINE_RATE environment variable.
The variable is in milliseconds, so to set 1 block per 10 seconds use:
EPOCH_MINE_RATE=10000 docker-compose up