Community Node Onboarding

Run Your Own Vorliq Node

A Vorliq node runs the blockchain API, backend API, public web app, and heartbeat service so the community can compare public state across independent operators.

Why It Helps

More independently operated nodes improve availability, make registry health easier to compare, and reduce dependence on a single public endpoint for bootstrap checks.

What You Need

Use a fresh Ubuntu 22.04 or 24.04 server with a public IP address, at least 1 GB RAM, 10 GB disk, a domain name, and access to change DNS records.

DNS and HTTPS

Your public node URL should be a domain you control, such as https://node.example.org. DNS must point to your server before Certbot can issue an HTTPS certificate. HTTPS helps browsers, wallets, and other operators verify they are talking to the expected host.

Verify Before Joining

Before a fresh node installs the app, it should verify a trusted public node with signed snapshot checks. The installer does this first and stops if the trusted node cannot be verified.

node tools/bootstrap_verify_node.js https://vorliq.org

Install With The Verified Installer

Run the installer as root on a fresh Ubuntu server. It asks for the trusted public node URL, your public node URL, display name, region, country, and optional operator wallet address.

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 installer verifies first, installs Node.js 20, Python 3.12, nginx, Certbot, Git, app dependencies, systemd services, nginx routing, and then runs a one-shot heartbeat registration.

Verified Chain Bootstrap

After the trusted public node verifies, the installer asks whether to run a dry-run chain bootstrap. Dry-run is the default and writes nothing. It checks the signed snapshot, audit manifest, chain export hash, block hashes, previous-hash links, latest hash, transaction ordering, and public-data secret scan.

python3.12 tools/bootstrap_chain_from_public_node.py --trusted-node https://vorliq.org --data-dir /home/vorliq/app/blockchain/data

Write mode is off by default. Use it only for a new node or after a deliberate backup. See the Verified Chain Bootstrap guide before using force mode manually.

Check The Node

Run the doctor after install or after updates. It is read-only and prints PASS, WARN, or FAIL with suggested commands when possible.

cd /home/vorliq/app
node tools/node_doctor.js --base-url http://127.0.0.1:5000 --public-url https://node.example.org --trusted-node https://vorliq.org

Open Node Sync to compare your node with the trusted public chain. behind means your node is lower, ahead is not automatically trusted, forked requires recovery checks, stale usually needs heartbeat or DNS repair, and unreachable means diagnostics could not be checked.

Update Safely

Back up first, then update code and rebuild dependencies. Do not delete blockchain/data, rewrite historical blocks, change block hashes, or switch storage backend during a routine update.

cd /home/vorliq/app
sudo bash deployment/update_server.sh
node tools/node_doctor.js --base-url http://127.0.0.1:5000 --public-url https://node.example.org

Read Logs

Use systemd logs for service health. Share summaries, not raw logs, when asking for public help.

sudo journalctl -u vorliq-backend.service -f
sudo journalctl -u vorliq-blockchain.service -f
sudo journalctl -u vorliq-heartbeat.service -f

Back Up Node Data

Back up the blockchain data folder before updates, server moves, or manual maintenance. Test restores on a separate machine before relying on a backup. Never restore over live data unless you have verified the backup and understand the impact.

sudo tar -czf vorliq-data-backup.tgz -C /home/vorliq/app/blockchain data

Keep Secrets Private

Do not publish private keys, admin tokens, snapshot signing keys, wallet passwords, SSH keys, environment files, raw logs, raw IP addresses, or raw user agents. Community nodes do not need snapshot signing private keys, and the verified installer does not create them.

What This Does Not Do

Running a node does not create legal, banking, financial, custody, investment, exchange, lending, or profit guarantees. Vorliq node checks are operational trust signals for open-source community software, not promises of value or future availability.