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 if you customized them at 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 (or in $BIN_DIR if specified)
  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 (or in $CONFIG_DIR if specified)
  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

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:

    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.

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.