Skip to main content
This guide walks you through manually building and running an Avail node from source code. This approach gives you full control over the build process and is ideal for development, debugging, or running custom configurations.

​
Prerequisites

Before building the Avail node, ensure you have the following dependencies installed:

​
Required Dependencies

1

Install Rust

Install Rust using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
The Avail node requires Rust version 1.82.0 as specified in rust-toolchain.toml.
2

Install Substrate Dependencies

Install the required system packages for building Substrate-based nodes:
sudo apt update
sudo apt install -y build-essential git clang curl libssl-dev llvm libudev-dev make cmake protobuf-compiler
3

Clone the Repository

Clone the Avail node repository:
git clone https://github.com/availproject/avail.git
cd avail
For a specific version, checkout the desired tag:
git checkout v2.3.4.0

​
Building the Node

​
Development Build

For testing and development (faster compilation, not optimized): 
cargo build

​
Production Build

For production use (optimized, slower compilation): 
cargo build --locked --release
The --locked flag ensures that dependencies match the versions in Cargo.lock, providing reproducible builds. The build process may take 20-40 minutes depending on your hardware.
The compiled binary will be located at:
  • Development: ./target/debug/avail-node
  • Release: ./target/release/avail-node

​
Running the Node

​
Create Data Directory

Before starting the node, create a directory to store blockchain data: 
mkdir -p output

​
Launch the Node

Connect to the Avail Mainnet:
cargo run --locked --release -- --chain mainnet -d ./output
Or using the compiled binary:
./target/release/avail-node --chain mainnet -d ./output

​
Common Launch Options

Customize your node startup with these common flags: 
./target/release/avail-node \
  --chain mainnet \
  -d ./output \
  --name "MyAvailNode" \
  --port 30333 \
  --rpc-port 9944 \
  --prometheus-port 9615 \
  --validator

​
Node Startup Output

When successfully started, you’ll see output similar to: 
2025-03-05 11:39:57 Avail Node    
2025-03-05 11:39:57 ✌️  version 2.3.0-6c6b8912fd3    
2025-03-05 11:39:57 ❤️  by Avail Project <[email protected]>, 2017-2025    
2025-03-05 11:39:57 📋 Chain specification: Avail Development Network    
2025-03-05 11:39:57 🏷  Node name: spotty-ducks-6306    
2025-03-05 11:39:57 👤 Role: AUTHORITY    
2025-03-05 11:39:57 💾 Database: ParityDb at /tmp/.../chains/.../paritydb/full    
2025-03-05 11:39:59 🏷  Local node identity is: 12D3KooW...    
2025-03-05 11:39:59 💻 Operating system: linux    
2025-03-05 11:39:59 💻 CPU: 13th Gen Intel(R) Core(TM) i7-13700K    
2025-03-05 11:39:59 💻 CPU cores: 16    
2025-03-05 11:39:59 💻 Memory: 31865MB    
2025-03-05 11:39:59 〽️ Prometheus exporter started at 127.0.0.1:9615    
2025-03-05 11:39:59 Running JSON-RPC server: addr=127.0.0.1:9944, allowed origins=["*"]    
2025-03-05 11:39:59 🏁 CPU score: 1.36 GiBs    
2025-03-05 11:39:59 🏁 Memory score: 22.37 GiBs    
2025-03-05 11:39:59 🏁 Disk score (seq. writes): 6.14 GiBs    
2025-03-05 11:39:59 🏁 Disk score (rand. writes): 2.85 GiBs
Hardware benchmarks are automatically run at startup unless you disable them with --no-hardware-benchmarks.

​
Data Directory Structure

The data directory (-d flag) contains:
  • chains/ - Blockchain data for each network
    • [chain-name]/db/ - Block database (ParityDB)
    • [chain-name]/keystore/ - Local key storage
    • [chain-name]/network/ - Peer-to-peer network data

​
Running as a Background Service

​
Using systemd

Create a systemd service file at /etc/systemd/system/avail-node.service: 
[Unit]
Description=Avail Node
After=network.target

[Service]
Type=simple
User=avail
WorkingDirectory=/home/avail
ExecStart=/home/avail/avail-node --chain mainnet -d /var/lib/avail --name "MyNode"
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
Enable and start the service: 
sudo systemctl daemon-reload
sudo systemctl enable avail-node
sudo systemctl start avail-node
sudo systemctl status avail-node
View logs: 
sudo journalctl -u avail-node -f

​
Troubleshooting

​
Build Errors

Ensure you’re using Rust 1.82.0:
rustup show
rustup update
The project’s rust-toolchain.toml should automatically select the correct version.
Reinstall system dependencies and ensure protoc is available:
protoc --version
Reduce parallel compilation jobs:
cargo build --locked --release -j 2

​
Runtime Issues

If you see database errors, the chain data may be corrupted. Purge the chain data and resync:
./target/release/avail-node purge-chain --chain mainnet -d ./output

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us