Skip to main content

Set Up a Full Node With Docker

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

Use Docker to Run an IOTA Full Node Locally

Use this guide to install and configure an IOTA Full Node locally using Docker for testing. The instructions apply to the following operating system and processor combinations:

  • Linux/AMD64
  • Darwin/AMD64
  • Darwin/ARM64

Prerequisites​

Before you begin, ensure you have the following:

Configure the IOTA Full Node​

Download the latest version of the IOTA Full Node configuration file fullnode-template.yaml. You can use the following command to download the file:

wget https://github.com/iotaledger/iota/raw/develop/crates/iota-config/data/fullnode-template.yaml

Add Peers​

For Testnet or Devnet nodes, edit the fullnode.yaml file to include peer nodes for state synchronization. Append the following to the end of the current configuration:

Devnet​

p2p-config:
    seed-peers:
    - address: /dns/access-0.r.devnet.iota.cafe/udp/8084
        peer-id: 01589ac910a5993f80fbc34a6e0c8b2041ddc5526a951c838df3037e11ab0188
    - address: /dns/access-1.r.devnet.iota.cafe/udp/8084
        peer-id: 32875c547ea3b44fa08a711646cedb70fa0c97959d236578131505da09723add

Testnet​

p2p-config:
    seed-peers:
    - address: /dns/access-0.r.testnet.iota.cafe/udp/8084
        peer-id: 46064108d0b689ed89d1f44153e532bb101ce8f8ca3a3d01ab991d4dea122cfc
    - address: /dns/access-1.r.testnet.iota.cafe/udp/8084
        peer-id: 8ffd25fa4e86c30c3f8da7092695e8a103462d7a213b815d77d6da7f0a2a52f5

Download the IOTA Genesis Blob​

The genesis blob defines the IOTA network configuration. Before starting the Full Node, download the latest genesis.blob file to ensure compatibility with your version of IOTA. Keep in mind that the IOTA Mainnet runs the Stardust Protocol at the moment, so only Testnet and Devnet blobs are available.

Start Your IOTA Full Node​

Run the following command to start the IOTA Full Node in Docker:

docker compose up

Important: 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 Full Node​

Run the following command to stop the Full Node when you finish using it:

docker compose stop

Test the IOTA Full Node​

After the Full Node starts, you can test the JSON-RPC interfaces.

Troubleshooting​

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

Start the Full Node in Detached Mode​

First, try starting the Full Node in detached mode:

docker compose up -d

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

Monitoring​

View Activity on Your Local Full Node with IOTA Explorer​

The IOTA Explorer supports connecting to any network as long as it has https enabled. To view activity on your local Full Node, open the URL: https://explorer.rebased.iota.org/, and select Custom RPC URL from the network dropdown in the top right.

View Resource Usage (CPU and Memory)​

To view resource usage details for the Full Node running in Docker, run the following command:

docker stats

This command shows a live data stream of the Docker container's resource usage, such as CPU and memory. To view data for all containers, use the following command:

docker stats -a

Inspect the State of a Running Full Node​

Get the running container ID:

docker ps

Connect to a bash shell inside the container:

docker exec -it $CONTAINER_ID /bin/bash

Inspect the database:

ls -la iotadb/

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-template.yaml
-json-rpc-address: "127.0.0.1:9000"
+json-rpc-address: "0.0.0.0:9000"

Question 1/3

In the context of IOTA Full nodes, what is the significance of the 2f+1 validators during transaction processing?