> ## Documentation Index > Fetch the complete documentation index at: https://sidiorresearchlabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Run a Node > Deploy RPC and Validator nodes on HyperPaxeer using the hpx CLI ## Overview The `hpx` CLI manages the full lifecycle of HyperPaxeer nodes — install, deploy, monitor, upgrade, and remove. Each node runs as an isolated Docker Compose stack with its own chain data, ports, and an FD Guardian sidecar that auto-restarts on file-descriptor leaks. *** ## 🚀 HyperPax Node: The Official "No-Headache" Setup Guide Setting up a node involves preparing your server, installing the HyperPax OS, and ensuring your node is visible for delegation. Follow these steps exactly to avoid the common `command not found` or `Docker missing` errors. ### Phase 1: Server Preparation Before running the main script, ensure your environment is clean. 1. **Log in as Root:** Most commands require administrative privileges. 2. **Verify Shell Path:** If you just installed the OS or shell updates, ensure your shell knows where to look for commands: ```bash theme={null} source ~/.bashrc ``` *Note: If you get a "No such file" error, don't panic. It just means you are using a clean shell that hasn't been modified yet.* *** ### Phase 2: Installing HyperPax-OS Run the installation script provided by the team. * **Pro Tip:** If the script asks to install Docker and seems "stuck," **wait**. Docker installation can take 2–5 minutes depending on the server's CPU and network speed. #### 🛠 Troubleshooting Common Install Errors If the installer fails on **Step 2/6 (Checking Dependencies)** with a `Missing: docker-compose-plugin` error: 1. **Manual Docker Compose Fix:** Run these commands one by one to manually place the plugin where the system expects it: ```bash theme={null} mkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose chmod +x ~/.docker/cli-plugins/docker-compose ``` 2. **System Tuning:** The script may ask: `Apply recommended system tuning? [y/N]`. * **Always Choose Y.** \* If you skip this, your node may hit "FD (File Descriptor) limits" and crash once the network load increases. *** ### Phase 3: Configuration & Data Sync Once the OS is installed, you need to configure your node. 1. **The Setup Command:** Type `hpx setup` to begin. 2. **Storage Location:** When asked `Where to store node data? [/root/hyperpax-nodes]`, simply **Press Enter** to use the default path. 3. **Syncing the Chain:** You will see a prompt for a `Chain data tarball URL`. * Unless you have been given a specific private link by the team, **Press Enter** to use the latest official snapshot. *** ### Phase 4: Activation & Delegation Your node is running, but it needs "Voting Power" to earn rewards. 1. **Get your IP and Port:** Find your node's connection string. It usually looks like this: `http://[YOUR_IP_ADDRESS]:[PORT]`. 2. **Send to the Registry:** Provide this URL to the network admin. This allows them to: * Add you to the official Registry. * **Delegate** staked coins to your node so you can begin validating blocks. *** ### 💡 Top 3 "Newbie" Tips from the Logs: * **Don't Spam Commands:** If you run the "longer script" multiple times, you might create conflicting directory paths (e.g., `/usr/bin/` vs `/root/`). Run it once and troubleshoot specific errors instead. * **The "hpx" Command:** If `hpx` isn't found immediately after installation, try running `source ~/.bashrc` again or logging out and back into your SSH session. * **Docker is Heavy:** If the screen says `Installing Docker...`, grab a coffee. Interrupting this process is the #1 cause of broken node environments. *** ## Requirements | Resource | Minimum | | -------- | ------------------------ | | RAM | 16 GB | | CPU | 6 cores | | Disk | 300 GB (SSD recommended) | | OS | Ubuntu 22.04+ | *** ## Install ```bash theme={null} curl -sSL https://hyperpaxeer.com/hyper-os/new/get-hpx.sh | sudo bash ``` The installer: 1. Checks system resources (RAM, CPU, disk) 2. Installs Docker, curl, jq, zstd if missing 3. Installs the `hpx` binary to `/usr/local/bin/` 4. Offers to run the **Setup Wizard** (system tuning, Docker image pull, capacity check) *** ## Deploy a Node ```bash theme={null} hpx deploy ``` | Type | Purpose | Configuration | | ----------- | ---------------------------------------- | ---------------------------------------- | | `rpc` | Serve JSON-RPC, gRPC, REST, WebSocket | Full indexing, all endpoints exposed | | `validator` | Produce blocks, participate in consensus | Default pruning, optimised for consensus | Examples: ```bash theme={null} hpx deploy my-rpc rpc hpx deploy mainnet-val validator ``` The CLI assigns ports automatically. Multiple nodes on one server get auto-incremented ports: | Protocol | Node 1 | Node 2 | Node 3 | | ------------ | ------ | ------ | ------ | | P2P | 26656 | 26756 | 26856 | | CometBFT RPC | 26657 | 26757 | 26857 | | REST API | 1317 | 1417 | 1517 | | gRPC | 9090 | 9190 | 9290 | | JSON-RPC | 8545 | 8645 | 8745 | | WebSocket | 8546 | 8646 | 8746 | *** ## Node Management | Command | Purpose | | -------------------- | -------------------------------- | | `hpx` | Interactive menu | | `hpx list` | List all registered nodes | | `hpx info ` | Sync status, block height, peers | | `hpx logs ` | Stream node logs | | `hpx start ` | Start a node | | `hpx stop ` | Stop a node | | `hpx restart ` | Restart a node | | `hpx start all` | Start all nodes | | `hpx stop all` | Stop all nodes | | `hpx remove ` | Delete a node and its data | | `hpx dashboard` | Live status dashboard | | `hpx capacity` | Show server resource usage | | `hpx setup` | Re-run the setup wizard | *** ## File Structure ``` /root/hyperpax-nodes/ .hpx-registry # tracks all nodes .hpx-setup-done # setup wizard completion marker my-rpc/ data/ # chain data + config scripts/ # start script + FD guardian logs/ # guardian logs docker-compose.yml # isolated compose stack ``` *** ## Create a Validator After your node syncs to the latest block, create a validator using the `hyperpaxd` binary inside the container: ```bash theme={null} hyperpaxd tx staking create-validator \ --amount=1000000ahpx \ --pubkey=$(hyperpaxd tendermint show-validator) \ --moniker="your-moniker" \ --chain-id=hyperpax_125-1 \ --commission-rate="0.05" \ --commission-max-rate="0.10" \ --commission-max-change-rate="0.01" \ --min-self-delegation="1000000" \ --gas="auto" \ --gas-prices="0.025ahpx" \ --from= ``` Ensure your server timezone is **UTC**. A different timezone can cause `LastResultsHash` mismatch errors that halt your node. *** ## Unjail a Validator If your validator is jailed for downtime (missing 500 of the last 10,000 blocks): ```bash theme={null} hyperpaxd tx slashing unjail \ --from= \ --chain-id=hyperpax_125-1 ``` *** ## Confirm Validator Status ```bash theme={null} hyperpaxd query tendermint-validator-set | grep "$(hyperpaxd tendermint show-address)" ``` Or check the [Network Status](/network-status) page for the current validator set. *** ## Troubleshooting **"Permission denied"** — Run with `sudo`. **"docker: denied"** — Stale credentials. Run `docker logout ghcr.io` and retry. **"Cannot connect to Docker daemon"** — Start Docker: `sudo systemctl start docker`. **Node stuck syncing** — Check peers with `hpx info `. If peers is 0, verify your firewall allows the P2P port. **"too many open files"** — The FD Guardian sidecar handles this automatically. If running outside Docker, increase limits: `ulimit -n 4096`. *** ## Update Re-run the installer to update to the latest version. Existing nodes and chain data are preserved: ```bash theme={null} curl -sSL https://hyperpaxeer.com/hyper-os/new/get-hpx.sh | sudo bash ``` *** ## Uninstall ```bash theme={null} curl -sSL https://hyperpaxeer.com/hyper-os/new/uninstall.sh | sudo bash ```