Skip to main content

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​

  • RAM: 64 GB
  • CPU: 8 physical cores / 16 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:

Default Firewall Ports

Make sure to open these ports in your firewall configuration.
(These are the defaults, but may vary for a custom setup)

Protocol/PortReachabilityPurposeDescription
TCP/8080OutboundValidator/transaction interfacefull nodes connect to validators to collect partial signatures for transactions
UDP/8084Inbound/OutboundPeer-to-peer state sync interfacenodes sync their state with each other
TCP/9000InboundJSON RPC endpoint / Web socket (optional)API for interaction with the network
TCP/9184LocalhostPrometheus metrics scrapingfor local monitoring only

Download the Full Node Docker Setup​

In a directory of your choice, run the following:

mkdir iota-fullnode-docker-setup && cd iota-fullnode-docker-setup && curl -L https://fullnode-docker-setup.iota.org/testnet | tar -zx

The command will perform the following steps:

  • creates and changes into the iota-fullnode-docker-setup directory
  • downloads the zipped configuration for the specific network, containing the docker-compose and node configuration files, and unzips them

You can modify the node configuration file (data/config/fullnode.yaml) according to your needs.

Prepare your Full Node​

Run the following command in the same directory:

./prepare.sh

This script will perform the following steps:

  • download the latest docker images specified in the docker-compose.yaml
  • download the network specific snapshot files that are needed to sync the node from genesis

Start your Full Node​

In the same directory, start your node by running:

docker compose up -d

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

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 Full Node Configuration​

By default, the configuration file fullnode.yaml is located at <your-fullnode-install-path>/data/config/.

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

    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

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

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

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 Full 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