Docker Setup

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

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

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.

Hardware requirements

Mainnet

• RAM: 64 GB
• CPU: 8 physical cores / 16 vCPUs
• Storage: 512 GB NVMe SSD (or more depending on pruning settings)
• Network Uplink: 1 Gbps

Testnet

• RAM: 32 GB
• CPU: 4 physical cores / 8 vCPUs
• Storage: 512 GB NVMe SSD (or more depending on pruning settings)
• Network Uplink: 1 Gbps

Software requirements

Before you begin, ensure you have the following:

• Docker installed.
• Docker Compose installed.

Default Firewall Ports

Make sure to open these ports in your firewall configuration.
(These are the defaults, but may vary if you customized them at setup)

Protocol/Port	Reachability	Purpose	Description
TCP/8080	Outbound	Validator/transaction interface	full nodes connect to validators to collect partial signatures for transactions
UDP/8084	Inbound/Outbound	Peer-to-peer state sync interface	nodes sync their state with each other
TCP/9000	Inbound	JSON RPC endpoint / Web socket (optional)	API for interaction with the network
TCP/9184	Localhost	Prometheus metrics scraping	for local monitoring only

Clone the IOTA repository

1. The first thing you need to do to set up your full node is clone the IOTA repository, you can use the following command or download it from GitHub:

git clone https://github.com/iotaledger/iota.git

2. Once you have download the source code, move into the docker fullnode directory:

cd iota/setups/fullnode/docker/

Configure the Full Node

Run the respective prepare script, depending on the network you want to run the Node on.

This will create the data folder and copy a template configuration into the config subfolder. You can modify this config file to your needs afterwards. The script will also download the necessary genesis.blob and optionally migration.blob for the network.

Testnet

If you want to run the Node on testnet, run the following command:

./prepare_testnet.sh

Devnet

If you want to run the Node on devnet instead, run the following command:

./prepare_devnet.sh

Start Your 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 Full Node

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

docker compose stop

Check your installation

Check your node configuration

By default, the configuration file fullnode.yaml is located at /opt/iota/config/fullnode.yaml.
You may have specified a different $CONFIG_DIR during setup.

The p2p section should include known public peer nodes, like this:

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

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

The archival section of the config file should look like this:

Testnet

state-archive-read-config:
  - object-store-config:
      object-store: "S3"
      aws-endpoint: "https://archive.testnet.iota.cafe"
      aws-virtual-hosted-style-request: true
      object-store-connection-limit: 20
      no-sign-request: true
    concurrency: 5
    use-for-pruning-watermark: false

Devnet

state-archive-read-config:
  - object-store-config:
      object-store: "S3"
      aws-endpoint: "https://archive.devnet.iota.cafe"
      aws-virtual-hosted-style-request: true
      object-store-connection-limit: 20
      no-sign-request: true
    concurrency: 5
    use-for-pruning-watermark: false

This allows nodes that fall behind to catch up by downloading archive data rather than relying on synchronization. See IOTA Archives for details.

Try reaching your node on the RPC endpoint

Your full node serves the read endpoints of the IOTA JSON-RPC API at: http://127.0.0.1:9000.

Register a new iota client environment with your node's RPC endpoint

iota client new-env --alias=local --rpc http://127.0.0.1:9000
iota client switch --env local

info

The instructions for building/installing the iota client are here

Then query the chain identifier from the RPC endpoint:

iota client chain-identifier