Skip to main content

Docker Setup

Advanced

These instructions are for setting up a full node for network participation. If you just need a local development environment, you should instead follow the instructions in Create a Local IOTA Network to create a local full node, validators, and faucet.

Minimum Hardware Requirements
  • CPUs: 8 physical cores / 16 vCPUs
  • RAM: 128 GB
  • Storage (SSD): 4 TB NVMe drive
Firewall Ports Information

The following table lists default ports used by the node software. Make sure to open these ports in your firewall configuration.

PortProtocolDescription
8084UDPThe external address other nodes can use to reach this node
9000TCPRPC endpoint (optional)
9184TCPThe port for Prometheus metrics (optional)

Prerequisites

Before you begin, ensure you have the following:

Setup

  1. Create a iota directory for the full node and navigate to it.
  2. Create a db directory for the node's database and
  3. Download the fullnode.yaml from Configuration page.
  4. Download the genesis.blob from Genesis page.
  5. Download docker-compose.yaml file with the following command:
wget https://github.com/iotaledger/iota/raw/develop/setups/fullnode/docker/docker-compose.yaml

Before going to the next step your setup directory might look like this:

    ├──opt
├──iota
├──db
├──fullnode.yaml
├──genesis.blob
├──docker-compose.yaml

Start the IOTA Full Node

Run the following command to start the full node in Docker in a detached mode:

docker compose up -d

You can check the logs of the full node by running the following command:

docker compose logs -f
tip

These commands assume you are using Docker Compose V2. In Docker Compose V1, the docker compose command uses a dash (docker-compose). If you use Docker Compose V1, replace the space in each docker compose command with a dash (docker-compose). For more information, see Docker Compose V2.

Stop the IOTA Full Node

Run the following command to stop the full node when you finish using it:

docker compose stop

Test and Monitor the IOTA Full Node

After the full node starts, you can test the JSON-RPC interfaces. Also, the best way to make sure your node is working correctly is to use monitoring tools, to learn more, check the Monitoring page.

Troubleshooting

If you encounter errors or your full node stops working, run the commands in the following section to resolve the issue.

Reset the Environment

If you continue to see issues, stop the full node (docker compose stop) and delete the Docker container and volume. Then run the following command to start a new instance of the full node using the same genesis blob:

docker compose down --volumes

Investigate Local RPC Connectivity Issues

Update the json-rpc-address in the full node config to listen on all addresses:

sed -i 's/127.0.0.1/0.0.0.0/' fullnode.yaml
-json-rpc-address: "127.0.0.1:9000"
+json-rpc-address: "0.0.0.0:9000"