Run a Public Vorliq Node

Quick Setup

The fastest way to deploy a Vorliq public node is to run the automated setup scripts on a fresh Ubuntu 22.04 server. The first command downloads and runs the installer. The second command runs the server configuration script from the cloned Vorliq repository.

curl -fsSL https://raw.githubusercontent.com/vorliq/Vorliq/main/deployment/setup_server.sh -o setup_server.sh
sudo bash setup_server.sh

sudo bash /home/vorliq/app/deployment/configure_server.sh

After the scripts finish, the React web app is served through nginx, the backend API runs through systemd, the blockchain API listens on port 5001, and the node is ready to register with the Vorliq community.

Advanced Manual Setup

The manual setup notes below explain what the automated scripts do and are useful for operators who want to customize the server, domain, SSL certificate, or systemd services by hand.

What You Need for Production

To run a public Vorliq node, use a Linux server running Ubuntu 22.04 or later with a public IP address, at least 1 gigabyte of RAM, and at least 10 gigabytes of disk space. A small virtual private server from a common provider is enough for early community nodes and usually costs around five dollars per month.

Install Dependencies on the Server

Install Git, Python, Node.js 20, npm, nginx, and the tools needed to create the Python virtual environment.

sudo apt update
sudo apt install -y git nginx software-properties-common python3.12 python3.12-venv python3-pip curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Clone and Configure Vorliq

Clone Vorliq, install the Python dependencies, install the Node.js backend, and build the React frontend. For a public node, configure the Flask blockchain API to listen on all interfaces by running it with VORLIQ_HOST=0.0.0.0 and port 5001.

git clone https://github.com/vorliq/Vorliq.git
cd Vorliq/blockchain
python3.12 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd ../backend
npm install
cd ../frontend
npm install
npm run build

Run Vorliq as a Service

Create one systemd service for the Flask blockchain API and one for the Node.js backend so both restart automatically if the server reboots or a process crashes.

[Unit]
Description=Vorliq Blockchain API
After=network.target

[Service]
WorkingDirectory=/home/ubuntu/Vorliq/blockchain
Environment=VORLIQ_HOST=0.0.0.0
Environment=VORLIQ_PORT=5001
ExecStart=/home/ubuntu/Vorliq/blockchain/.venv/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target

[Unit]
Description=Vorliq Backend API
After=network.target

[Service]
WorkingDirectory=/home/ubuntu/Vorliq/backend
Environment=PORT=5000
Environment=FLASK_URL=http://127.0.0.1:5001
ExecStart=/usr/bin/node index.js
Restart=always

[Install]
WantedBy=multi-user.target

Public node operators can add optional registry identity environment variables to the backend service. These values are public metadata used by the heartbeat script and should not contain secrets.

Environment=VORLIQ_NODE_URL=https://node.example.org
Environment=VORLIQ_NODE_NAME=Example Vorliq Node
Environment=VORLIQ_NODE_REGION=Europe
Environment=VORLIQ_NODE_COUNTRY=United Kingdom
Environment=VORLIQ_OPERATOR_WALLET=VLQ_PUBLIC_OPERATOR_ADDRESS

Operator Admin Token

Production incident and operator dashboard routes are protected by ADMIN_TOKEN. The automated deployment creates a strong random token in /etc/vorliq/backend.env when one is not already present and loads it through the backend systemd service. Do not commit this token, print it in logs, or share it publicly.

sudo mkdir -p /etc/vorliq
sudo sh -c 'umask 077 && printf "ADMIN_TOKEN=%s\n" "$(openssl rand -hex 32)" > /etc/vorliq/backend.env'
sudo systemctl daemon-reload
sudo systemctl restart vorliq-backend.service

The backend service should include EnvironmentFile=-/etc/vorliq/backend.env or an equivalent Environment=ADMIN_TOKEN=... line in /etc/systemd/system/vorliq-backend.service. Use the environment file when possible so the token is not copied into documentation or shell history.

Operators can use this token privately with the protected dashboard at https://vorliq.org/admin and the incident API described in the incident response guide.

Configure nginx

Use nginx to serve the React frontend and proxy backend API requests. Replace the server name with your domain or public IP address.

server {
  listen 80;
  server_name your-domain-or-ip;

  root /home/ubuntu/Vorliq/frontend/build;
  index index.html;

  location / {
    try_files $uri /index.html;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:5000/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

Open Your Node to the Network

After the server is running, open port 5001 for peer blockchain communication and port 80 for the web app. Register your node in the Vorliq Registry page using your public IP address and port 5001, then share the node URL in the Vorliq Discord and Telegram so community members can connect.