FluxOS Setup Guide

FluxOS Setup Guide

This guide walks you through a complete FluxOS node installation from a fresh server to a fully operational node on the Flux network. The process involves preparing your server, installing FluxOS using the official multinode setup tool, configuring your node identity, and verifying that everything is running correctly.

Prerequisites

• •Operating System: Ubuntu 22.04 LTS (recommended). Ubuntu 20.04 LTS is also supported. Other Debian-based distributions may work but are not officially supported.
• •Fresh Server: Start with a clean OS installation. Running FluxOS alongside other services can cause resource contention and benchmark failures.
• •Root Access: You need root or sudo access to install packages, configure the firewall, and run the installation script.
• •Public IPv4 Address: Your server must have a dedicated public IPv4 address reachable from the internet.
• •Collateral: The required FLUX collateral must be held in your Zelcore or SSP Wallet (1,000 for Cumulus, 12,500 for Nimbus, 40,000 for Stratus).
• •Zel ID: A Zel ID registered through Zelcore wallet, which serves as your node operator identity.

Step 1: System Preparation

Begin by updating your server packages and performing basic system hardening. Connect to your server via SSH as root or a sudo-enabled user.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git

Set your system timezone and ensure the clock is synchronized. Accurate time is important for node communication and benchmark scheduling.

sudo timedatectl set-timezone UTC
sudo apt install -y chrony
sudo systemctl enable chrony
sudo systemctl start chrony

Step 2: Configure Firewall

FluxOS requires specific ports to be open for communication. The key ports are 16124-16129 for FluxOS API and inter-node communication, and 16132 for the FluxOS UI dashboard. Port 16125 is used by the Flux daemon for peer-to-peer blockchain communication.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 16124:16129/tcp
sudo ufw allow 16132/tcp
sudo ufw enable

Step 3: Run the FluxOS Installation Script

The Flux team maintains an official multinode setup tool (multitoolbox) on GitHub that automates the installation of FluxOS, the Flux daemon, MongoDB, and all required dependencies. This is the recommended installation method.

bash -i <(curl -s https://raw.githubusercontent.com/RunOnFlux/fluxnode-multitool/master/multitoolbox.sh)

The multitool presents an interactive menu. Select the option to install a new Flux node. The script will guide you through the installation process, which typically takes 15-30 minutes depending on your server speed and network connection. The installer will:

1. 1

   Install system dependencies

   Docker, MongoDB, Node.js, and other required packages are installed and configured automatically.

2. 2

   Install and sync the Flux daemon

   The Flux blockchain daemon (fluxd) is installed and begins syncing with the network. A bootstrap file may be used to accelerate initial sync.

3. 3

   Install FluxOS

   The FluxOS application layer is cloned from GitHub and configured on your server.

4. 4

   Prompt for your Zel ID

   You will be asked to enter your Zel ID (found in Zelcore wallet under Apps > Zel ID).

Step 4: Identity and Collateral Configuration

During installation, you need to configure your node identity. This involves your Zel ID and your collateral transaction.

• •Zel ID: Your unique operator identity from Zelcore wallet. This is a long alphanumeric string that links the node to your wallet.
• •Identity Key (znodePrivKey): Generated during setup, this key authenticates your node to the network. Keep this key secure and backed up.
• •Collateral Transaction (znodeoutpoint): The transaction ID and output index of your collateral FLUX held in Zelcore. This is obtained from Zelcore by going to the Flux app, selecting "Nodes", and viewing your collateral output.

Step 5: Start the Node

After installation completes, the Flux daemon and FluxOS should start automatically. You can verify the services are running and check the blockchain sync status.

# Check if fluxd is running
flux-cli getinfo

# Check blockchain sync status
flux-cli getblockchaininfo

# Check FluxOS status
pm2 list

Once you confirm the daemon is running, you need to start the node from your Zelcore wallet. In Zelcore, go to Apps > Flux Nodes, select your node, and click "Start Node". This broadcasts a transaction to the network announcing your node.

Step 6: Verify Node Status

You can access the FluxOS UI dashboard by navigating to your server IP on port 16126 in a web browser. This provides a real-time overview of your node status, benchmark results, connected peers, and deployed applications.

http://YOUR_SERVER_IP:16126

You can also verify node status via the command line API or by using the Flux daemon CLI tools.

# Check node status
flux-cli getzelnodestatus

# Expected output for a running node:
# "status": "CONFIRMED"

# Check benchmark status
fluxbench-cli getbenchmarks

Step 7: Wait for Blockchain Sync

The Flux blockchain must fully synchronize before your node becomes operational on the network. Initial sync can take several hours depending on your server speed and network connection. The multitool installer typically downloads a bootstrap to accelerate this process, but you should monitor progress.

# Watch sync progress (block count should increase and match the network)
watch -n 10 flux-cli getblockcount

# Compare against the network block height
flux-cli getblockchaininfo | grep -E "blocks|headers"

Common Issues and Troubleshooting

1. 1

   Node stuck on "STARTED" instead of "CONFIRMED"

   The blockchain is still syncing or the node has not been recognized by the network yet. Wait for full sync and allow up to 2 hours for confirmation. Verify your collateral transaction is correct.

2. 2

   Benchmark failures after installation

   Check that your hardware meets the minimum requirements for your chosen tier. Run "fluxbench-cli getbenchmarks" to see which specific test is failing (CPU, RAM, SSD, or bandwidth).

3. 3

   Port not reachable

   Verify UFW rules are correct. Check that your hosting provider does not have an external firewall blocking the required ports. Use "sudo ufw status verbose" to confirm rules.

4. 4

   FluxOS UI not loading

   Ensure port 16126 is accessible. Check that FluxOS is running with "pm2 list". If the FluxOS process is stopped, restart it with "pm2 restart flux".

5. 5

   Daemon crashes or high memory usage

   Ensure your server has sufficient RAM for the chosen tier, plus overhead for the OS and FluxOS. A Cumulus node typically uses 5-6 GB of RAM total. Check system resources with "htop".