Skip to main content

Docker Setup

Use this guide to install and configure an full node locally using 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.

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/mainnet | 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

Configure P2P Settings​

Configure the P2P settings in your fullnode.yaml file by following these steps:

  1. Update the external address:
p2p-config:
  external-address: /dns/<YOUR-DOMAIN>/udp/8084
note

Replace <YOUR-DOMAIN> with your public hostname. In case you don't have a public hostname, you can alternatively use a public IPv4 like /ip4/1.2.3.4/udp/8084/ or IPv6 like /ip6/2001:db8::1234:5678/udp/8084

This address must be accessible from the internet.

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/.

If you changed your local configuration you can always go back to the default Full Node Configuration.

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