Skip to main content

Build From Source

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

1. Software requirements​

  • Linux (recommended):
    • For this installer to work, use a Linux distribution with systemd and apt-get.
    • IOTA recommends and supports Ubuntu or Debian.
    • Building from source also works on macOS (but systemd-related steps won't).
  • Rust/cargo stable (recent version, check rust-toolchain.toml for the specific version) . If needed, update Rust.
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

2. Run the installer script​

In any directory, run:

NETWORK="testnet" bash -i <(curl -sSf https://raw.githubusercontent.com/iotaledger/iota/refs/heads/develop/setups/fullnode/systemd/setup.sh)
info

Set the network environment variable to the network you want to connect to ("testnet", "mainnet", or "devnet")

The installer will perform the following steps:

  1. Check your rust toolchain version
  2. Install system packages (libraries & other dependencies):
    tzdata, libprotobuf-dev, ca-certificates, build-essential, libssl-dev, libclang-dev, libpq-dev, pkg-config, openssl, protobuf-compiler, git, clang, cmake
  3. Clone the iota repo, set to the right branch for the network you chose
  4. Build the iota-node binary
    The built binary is located at /opt/iota/bin/iota-node by default.
  5. Create a user called iota, make it own directories for service binary, config, data
  6. Create a node config file, download genesis/migration blobs
    The config and blob files are located at /opt/iota/config by default.
  7. Create a systemd service unit file
    The service definition file is located at /etc/systemd/system/iota-node.service.
  8. Start the service

3. Check your installation​

Your IOTA node should now be running and connected to the network you chose.

Check that the iota-node service is active and running:

sudo systemctl status iota-node

Check (and follow) the logs:

journalctl -u iota-node -f

If you need to stop the service, you can run sudo systemctl stop iota-node

Your IOTA node should now be running and connected to the network you chose.

Check your node configuration​

By default, the configuration file fullnode.yaml is located at /opt/iota/config/fullnode.yaml.

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

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.

Reach your node via 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

Troubleshooting​

If you run into issues during the setup, or while checking your install, be sure to check common issues in the troubleshooting section

4. Updating Your Full Node​

When IOTA releases a new version, you must update your full node with the release to ensure compatibility with the network it connects to.
Make sure your node stays on the same network (testnet, mainnet, devnet, ...) it was previously connected to.

To upgrade your node, run the same script you used to install it:

NETWORK="testnet" bash -i <(curl -sSf https://raw.githubusercontent.com/iotaledger/iota/refs/heads/develop/setups/fullnode/systemd/setup.sh)
info

Re-use the same network (testnet, mainnet, devnet) your node is already running on.

Your full node restarts on: http://127.0.0.1:9000.

info

If your full node is configured to prune transactions, Archival nodes can help ensure lagging peer nodes don't lose any information. For more information, see IOTA Archives.

5. Customize your node's configuration​

warning

Node logs can take a lot of space quickly. Make sure to configure your iota-node systemd service to rotate or prune logs to not run out of space. See systemd docs

You can also lower the log level by editing your service definition file (changing RUST_LOG in /etc/systemd/system/iota-node.service), in order to produce less logs.

In the next section, we'll see which options are available to tune the node's configuration to your preferences.