Using Docker

Bee Docker images (amd64/x86_64 architecture) are available at iotaledger/bee on Docker Hub.

Requirements

1. A recent release of Docker enterprise or community edition. You can find installation instructions in the official Docker documentation.
2. GIT
3. At least 1GB available RAM

Clone the Repository

Once you have completed all the installation requirements, you can clone the repository by running:

git clone https://github.com/iotaledger/bee
cd bee/

info

The next portion of the guide assumes you are executing commands from the root directory of the repository.

Prepare

Choose the config.json for the network that you want to join: and copy it to /.config.json:

cp ./config.chrysalis-<insert network here>.json config.json. 

If you want to use alternative ports, edit the config.json file.

Run

You can pull the latest image from iotaledger/bee public Docker Hub registry by running:

docker pull iotaledger/bee:latest && docker tag iotaledger/bee:latest bee:latest

We recommend that you run on host network to improve performance. Otherwise, you are going to have to publish ports using iptables NAT which is slower.

docker run \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v $(pwd)/storage:/app/storage \
  -v $(pwd)/snapshots:/app/snapshots \
  --name bee\
  --net=host \
  --ulimit nofile=8192:8192 \
  -d \
  bee:latest

• $(pwd) Stands for the present working directory. All mentioned directories are mapped to the container, so the Bee in the container persists the data directly to those directories.
• -v $(pwd)/config.json:/app/config.json:ro Maps the local config.json file into the container in readonly mode.
• -v $(pwd)/storage:/storage Maps the local storage directory into the container.
• -v $(pwd)/snapshots:/snapshots Maps the local snapshots directory into the container.
• --name bee Name of the running container instance. You can refer to the given container by this name.
• --net=host Instructs Docker to use the host's network, so the network is not isolated. We recommend that you run on host network for better performance. This way, the container will also open any ports it needs on the host network, so you will not need to specify any ports.
• --ulimit nofile=8192:8192 increases the ulimits inside the container. This is important when running with large databases.
• -d Instructs Docker to run the container instance in a detached mode (daemon).

You can run docker stop -t 300 bee to gracefully end the process.

Create Username and Password for the Bee Dashboard

If you use the Bee dashboard, you need to create a secure password. Start your Bee container and execute the following command when the container is running:

docker exec -it bee password

Expected output:

Password: [enter password]
Re-enter password: [enter password]
Password salt: [password salt]
Password hash: [password hash]

You can edit config.json and customize the dashboard section to your needs.

"dashboard": {
    "bindAddress": "/ip4/0.0.0.0/tcp/8081",
    "auth": {
      "sessionTimeout": 86400,
      "user": "admin",
      "passwordSalt": "[password salt]",
      "passwordHash": "[password hash]"
    }
  }

Build Your Own Bee Image

You can build your own Docker image by running the following command:

docker build -f bee-node/docker/Dockerfile -t bee:latest .

Or pull it from Docker Hub (only available for amd64/x86_64):

docker pull iotaledger/bee:latest && docker tag iotaledger/bee:latest bee:latest

Managing a Node

info

Bee uses an in-memory cache. In order to save all data to the underlying persistent storage, it is necessary to provide a grace period of at least 200 seconds while shutting it down.

Starting an Existing Bee Container

You can start an existing Bee container by running:

docker start bee

Restarting Bee

You can restart an existing Bee container by running:

docker restart -t 300 bee

• -t 300 Instructs Docker to wait for a grace period before shutting down.

Stopping Bee

You can stop an existing Bee container by running:

docker stop -t 300 bee

• -t 300 Instructs Docker to wait for a grace period before shutting down.

Displaying Log Output

You can display an existing Bee containers logs by running:

docker logs -f bee

• -f Instructs Docker to continue displaying the log to stdout until CTRL+C is pressed.

Removing a Container

You can remove an existing Bee container by running:

docker container rm bee

Setup using docker-compose

You can keep track of different configurations of the node using the docker-compose. An example docker-compose.yml is in ./bee-node/docker/, if you just quickly want to try out the node software on its own.

If you want to run the latest release from Docker Hub you can call:

docker-compose -f bee-node/docker/docker-compose.yml up --no-build

Or, if you want to build the latest version of Bee from source, you can use:

docker-compose -f bee-node/docker/docker-compose.yml up --build