Vorliq Home

Run a Public Vorliq Node

Deploy the Version 1.0 blockchain and backend on an Ubuntu server.

Quick Setup

Community operators should start with the verified installer in the Run Your Own Node guide. It verifies the trusted public node before installing, offers a dry-run verified chain bootstrap, preserves existing data, avoids creating snapshot signing keys, and does not create an admin token unless the operator explicitly asks.

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

The older setup and configure scripts remain useful for production-maintainer deployments, but they are not the recommended first path for non-expert community operators.

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 with operator-chosen bind host and port settings such as VORLIQ_HOST=example-bind-address and VORLIQ_PORT=example-port.

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=/path/to/vorliq/blockchain
Environment=VORLIQ_HOST=example-bind-address
Environment=VORLIQ_PORT=example-port
ExecStart=/path/to/vorliq/blockchain/.venv/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target
[Unit]
Description=Vorliq Backend API
After=network.target

[Service]
WorkingDirectory=/path/to/vorliq/backend
Environment=PORT=example-port
Environment=FLASK_URL=https://community-node.example
ExecStart=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.

VORLIQ_NODE_URL: https://node.example.org
VORLIQ_NODE_NAME: Example Vorliq Node
VORLIQ_NODE_REGION: Example Region
VORLIQ_NODE_COUNTRY: Example Country
VORLIQ_OPERATOR_WALLET: VLQ_PUBLIC_OPERATOR_ADDRESS

Upgrade Existing Nodes

If you already operate a Vorliq node, read the Upgrade Guide before pulling new code. Back up first, update with the server script when available, then verify /api/version/metadata, /api/storage/health, /api/audit/manifest, and /api/readiness.

Production Readiness Gate

After deployment, operators should check the public readiness endpoint and app page. The score combines health, deployment commit, API version, security posture, storage, backups, incidents, audit manifest, network manifest, registry activity, chain validity, mining, treasury, faucet, analytics, admin route protection, and version metadata.

node tools/check_readiness.js https://vorliq.org --allow-warning

A pass result means the technical release gate is healthy. A warning means operators should review the listed checks before declaring the release complete. A fail result should block release promotion until the critical or high-risk issue is corrected. Readiness is not a legal, banking, financial, or investment guarantee.

Signed Public Snapshots

Vorliq production snapshots are signed, and required signatures should remain enabled after live verification. Generate keys locally or on the server, store the private key only as a protected backend secret, and publish only the public key and key id. Do not commit the private key, add it to frontend code, paste it into public logs, or put it in deployment docs.

node tools/generate_snapshot_keypair.js

# Add these securely to a private environment file outside the repository:
VORLIQ_SNAPSHOT_PRIVATE_KEY: redacted
VORLIQ_SNAPSHOT_PUBLIC_KEY: redacted
VORLIQ_REQUIRE_SNAPSHOT_SIGNATURE: true

sudo systemctl restart vorliq-backend.service
node tools/verify_snapshot.js https://vorliq.org
node tools/verify_snapshot.js https://vorliq.org --require-signature
curl https://vorliq.org/api/snapshot/public-key

The file should be root-owned with restrictive permissions, and the backend service should load it from a private operator-controlled location. Set VORLIQ_REQUIRE_SNAPSHOT_SIGNATURE only after the signed snapshot verifies. In an emergency, disable the requirement privately, restart, and report the reason. Rotate keys by publishing the new public key id, updating the backend secrets, restarting the backend, and keeping prior public keys documented for historical verification. Signed snapshots prove snapshot provenance from the configured signing key; they do not prove legal, banking, financial, or investment status.

Operator Admin Token

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

sudo systemctl daemon-reload
sudo systemctl restart vorliq-backend.service

The backend service should load the admin token from a private operator-controlled environment file. 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 /path/to/vorliq/frontend/build;
  index index.html;

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

  location /api/ {
    proxy_pass https://community-node.example/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 so community members can connect.