XBerry Docs

Appearance

AR.IO Node Linux Installation Guide ​

Overview ​

The following instructions will guide you through the process of installing the AR.IO node on a Linux machine, specifically Ubuntu 22.04.3 desktop on a home computer. Actual steps may differ slightly on different versions or distributions. This guide covers how to set up your node, point a domain name to your home network, and create an nginx server for routing traffic to your node. No prior coding experience is required.

System Requirements ​

Please note: The AR.IO Node software is still in development and testing, all system requirements are subject to change.

External storage devices should be formatted as ext4.

Minimum Requirements ​

The hardware specifications listed below represent the minimum system requirements at which the AR.IO Node has been tested. While your Node may still operate on systems with lesser specifications, please note that AR.IO cannot guarantee performance or functionality under those conditions. Use below-minimum hardware at your own risk.

  • 4 core CPU
  • 4 GB RAM
  • 500 GB storage (SSD recommended)
  • Stable 50 Mbps internet connection
  • 12 core CPU
  • 32 GB RAM
  • 2 TB SSD storage
  • Stable 1 Gbps internet connection

Quick Installation ​

If you would like to quickly install all required and suggested packages, you can run the following 4 commands in your terminal, and skip to installing the Node.

bash
sudo apt update -y && sudo apt upgrade -y && sudo apt install -y curl openssh-server git certbot nginx sqlite3 build-essential && sudo systemctl enable ssh && curl -sSL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - && echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list && sudo apt-get update -y && sudo apt-get install -y yarn && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash && source ~/.bashrc && sudo ufw allow 22 80 443 && sudo ufw enable
bash
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
bash
nvm install 20.11.1 && nvm use 20.11.1

Detailed Installation ​

Required Packages ​

  1. Update your software:

    bash
    sudo apt update
sudo apt upgrade

  2. Enable your firewall and open necessary ports:

    bash
    sudo ufw enable

# Optional: If using SSH, allow port 22
sudo ufw allow 22

# Allow ports 80 and 443 for HTTP and HTTPS
sudo ufw allow 80
sudo ufw allow 443

  3. Install nginx:

    bash
    sudo apt install nginx -y

  4. Install git:

    bash
    sudo apt install git -y

  5. Install Docker:

    bash
    # Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
    bash
    sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  6. Test Docker installation:

    bash
    sudo docker run hello-world

  7. Install Certbot:

    bash
    sudo apt install certbot -y

Suggested Packages ​

These packages are not required to run a node in its basic form. However, they will become necessary for more advanced usage or customization.

  1. Install SSH (optional, for remote access to your Linux machine):

    bash
    sudo apt install openssh-server -y
sudo systemctl enable ssh

  2. Install Yarn:

    bash
    curl -sSL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update -y
sudo apt-get install yarn -y

  3. Install NVM (Node Version Manager):

    bash
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

  4. Install Node.js:

    bash
    nvm install 20.11.1

  5. Install build tools:

    bash
    sudo apt install build-essential

  6. Install SQLite:

    bash
    sudo apt install sqlite3 -y

Install the AR.IO Node ​

  1. Navigate to the desired installation location:

    NOTE: Your database of Arweave Transaction Headers will be created in the project directory, not Docker. So, if you are using an external hard drive to turn an old machine into a node, install the node directly to that external drive.

  2. Clone the ar-io-node repository and navigate into it:

    bash
    git clone -b main https://github.com/ar-io/ar-io-node
cd ar-io-node

  3. Create an environmental variables file:

    bash
    nano .env

  4. Paste the following content into the new file, replacing <your-domain> with the domain address you are using to access the node, and <your-public-wallet-address> with the public address of your Arweave wallet:

    GRAPHQL_HOST=arweave.net
GRAPHQL_PORT=443
START_HEIGHT=0
RUN_OBSERVER=true
ARNS_ROOT_HOST=<your-domain>
AR_IO_WALLET=<your-public-wallet-address>
OBSERVER_WALLET=<hot-wallet-public-address>

    Notes on Configuration Parameters:

    • The GRAPHQL values set the proxy for GQL queries to arweave.net. You may use any available gateway that supports GQL queries. If omitted, your node can support GQL queries on locally indexed transactions, but only L1 transactions are indexed by default.
    • START_HEIGHT is an optional line. It sets the block number where your node will start downloading and indexing transactions headers. Omitting this line will begin indexing at block 0.
    • RUN_OBSERVER turns on the Observer to generate Network Compliance Reports. This is required for full participation in the AR.IO Network. Set to false to run your gateway without Observer.
    • ARNS_ROOT_HOST sets the starting point for resolving ARNS names, which are accessed as a subdomain of a gateway. It should be set to the URL you are pointing to your node, excluding any protocol prefix. For example, use node-ar.io and not https://node-ar.io. If you are using a subdomain to access your node and do not set this value, the node will not understand incoming requests.
    • AR_IO_WALLET is optional, and sets the wallet you want associated with your Gateway. An associated wallet is required to join the AR.IO network.
    • OBSERVER_WALLET is the public address of the wallet used to sign Observer transactions. This is required for Observer to run, but may be omitted if you are running a gateway outside of the AR.IO network and do not plan to run Observer. You will need to supply the keyfile to this wallet in the next step.
    • Advanced configuration options can be found at docs.ar.io

  5. Supply Your Observer Wallet Keyfile: If you are running Observer, you need to provide a wallet keyfile in order to sign report upload transactions. The keyfile must be saved in the wallets directory in the root of the repository. Name the file &lt;Observer-Wallet-Address&gt;.json, replacing "<Observer-Wallet-Address>" with the public address of the wallet. This should match your OBSERVER_WALLET environmental variable.

    Learn more about creating Arweave wallets and obtaining keyfiles from the AR.IO documentation.

  6. Start the Docker container:

    bash
    sudo docker compose up -d

    Explanation of flags:

    • up: Start the Docker containers.
    • -d: Run the containers as background processes (detached mode).

    NOTE: Effective with Release #3, it is no longer required to include the --build flag when starting your gateway. Docker will automatically build using the image specified in the docker-commpose.yaml file.

  7. To shut down your gateway, run the command:

    bash
    sudo docker compose down

  8. To ensure your node is running correctly, check the logs for errors:

    bash
    sudo docker compose logs -f --tail=0

    Explanation of flags:

    • -f: Follow the logs in real time.
    • --tail=0: Ignore all logs from before running the command.

    NOTE: Previous versions of these instructions advised checking a gateway's ability to fetch content using localhost. Subsequent security updates prevent this without first disabling ARNS_ROOT_HOST in your .env.

Set up Networking ​

The following guide assumes you are running your node on a local home computer.

Register a Domain Name ​

Choose a domain registrar (e.g., Namecheap) to register a domain name.

Point the Domain at Your Home Internet ​

  1. Obtain your public IP address by visiting https://www.whatsmyip.org/ or running:

    bash
    curl ifconfig.me

  2. Create an A record with your registrar for your domain and wildcard subdomains, using your public IP address. For example, if your domain is "ar.io," create a record for "ar.io" and "*.ar.io."

Set up Port Forwarding ​

  1. Obtain the local IP address of the machine where the node is installed by running:

    bash
    ip addr show | grep -w inet | awk '{print $2}' | awk -F'/' '{print $1}'

    If there are multiple lines of output, choose the one starting with 192 (usually).

  2. Access your router's configuration:

    • Enter your router's IP address in the address bar of a browser (e.g., 192.168.0.1).
    • If you're unsure of your router's IP address, consult your router's documentation or contact your Internet Service Provider (ISP).

  3. Navigate to the port forwarding settings in your router configuration.

    • The exact steps may vary depending on your router model. Consult your router's documentation or support for detailed steps.

  4. Set up port forwarding rules to forward incoming traffic on ports 80 (HTTP) and 443 (HTTPS) to the same ports on the machine running your node. You may also forward port 22 if you want to enable SSH access to your node from outside your home network.

Create SSL (HTTPS) Certificates for Your Domain ​

bash
sudo certbot certonly --manual --preferred-challenges dns --email &lt;your-email-address&gt; -d &lt;your-domain&gt;.com -d '*.&lt;your-domain&gt;.com'

Follow the instructions to create the required TXT records for your domain in your chosen registrar. Use a DNS checker to verify the propagation of each record. This can take some time.

IMPORTANT: Wild card subdomain (*.<your-domain>.com) cannot auto renew without obtaining an API key from your domain registrar. Not all registrars offer this. Certbot certificates expire every 90 days. Be sure to consult with your chosen registrar to see if they offer an API for this purpose, or run the above command again to renew your certificates. You will receive an email warning at the address you provided to remind you when it is time to renew.

Configure nginx ​

nginx is a free and open-source web server and reverse proxy server. It will handle incoming traffic, provide SSL certificates, and redirect the traffic to your node.

  1. Open the default configuration file:

    bash
    sudo nano /etc/nginx/sites-available/default

  2. Replace the file's contents with the following configuration (replace "(your-domain)" when necessary):

    nginx
    # Force redirects from HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name &lt;your-domain&gt;.com *.&lt;your-domain&gt;.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

# Forward traffic to your node and provide SSL certificates
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name &lt;your-domain&gt;.com *.&lt;your-domain&gt;.com;

    ssl_certificate /etc/letsencrypt/live/&lt;your-domain&gt;.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/&lt;your-domain&gt;.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
    }
}

  3. Test the configuration:

    bash
    sudo nginx -t

  4. If there are no errors, restart nginx:

    bash
    sudo service nginx restart

Your node should now be running and connected to the internet. Test it by entering https://&lt;your-domain&gt;/3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ in your browser.

Note: If you encounter any issues during the installation process, please seek assistance from the AR.IO community.