Skip to content
Hyperion

Add a worker node

A worker node runs the agent and hosts sites. The master drives it over signed requests on port 9443. You add one by creating an invite on the master and running the node installer on the new server.

Before you start

Section titled “Before you start”
  • You are signed in as an Owner. Only Owners see the Nodes page.
  • A fresh Debian 12 or newer server with root access and the requirements met, with free ports 80 and 443 and the RPC port (9443).
  • The new server can reach the master’s address over HTTPS, and the master can reach the new server on port 9443.
  • A panel domain is set, so the node can verify the master’s certificate. See Set or move the panel domain. With a self-signed certificate on the master, the installer writes verify_tls = false.

Steps

Section titled “Steps”

  1. On the master, open Nodes in the sidebar and scroll to Add a node (the Add a node button at the top jumps there).

  2. Under 1 · Create an invite, enter a Label for the node, such as node5.example.com. Set Token expires after in hours (1 to 720, default 24).

  3. Check Master URL the new node calls back to. It is taken from the address in your browser. Change it if the new server reaches the master by another name. The command updates as you type.

  4. Click Create invite. The page shows Invite created for the label and a command. The token is shown once and only its hash is stored. Click Copy install command, or Reveal token to see it.

  5. On the new server, as root, paste and run the command. It has this form:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/nechodom/hyperion/main/packaging/install/install-node.sh \
      | sudo bash -s -- --token=<token> --master=https://panel.example.com

  6. Answer the prompts, or set the variables first to skip them. Setting HYPERION_NONINTERACTIVE=1 accepts the defaults.

    Prompt Variable Default
    Install MariaDB HYPERION_WITH_MARIADB=0 or 1 yes
    Install PostgreSQL HYPERION_WITH_POSTGRES=0 or 1 yes
    Install vsftpd HYPERION_WITH_VSFTPD=0 or 1 yes
    FTP control port HYPERION_FTP_PORT 21
    master to node RPC port HYPERION_RPC_PORT 9443
    Private IP for master and node RPC HYPERION_ADVERTISE_ADDR blank: listen on all addresses, use the public IP

    Give a private address if the master and node share a private network. The agent then listens on that address only. The node’s name comes from --label=<name> or HYPERION_NODE_LABEL, and defaults to the server’s host name.

  7. The installer checks the ports first, installs nginx, PHP 8.3, the chosen database and FTP software, wp-cli and phpMyAdmin, compiles hyperion-agent and hctl, writes /etc/hyperion/agent.toml with the invite and starts the agent. If ufw is active, it opens the RPC port to the master only, or to the /24 of a private address. If it cannot determine the master’s address, it opens the port to any source and prints a warning. Scope it then with sudo ufw delete allow 9443/tcp and sudo ufw allow proto tcp from <master-ip> to any port 9443, using your RPC port. It ends with the box Hyperion node provisioned.

Check that it worked

Section titled “Check that it worked”

On the new server:

Terminal window
hctl info

Expected: no NOT ENROLLED message.

On the master, the node appears in the Nodes list, with its public IP and agent version. Its dot is on, and seen shows a recent time. Open the row and click Test connection. It reports the answer from the agent on port 9443. After one more heartbeat the row shows TLS pin on file and Response auth on file. The invite disappears from 2 · Pending invites.

The new node is now offered in the create form of Add a website as Which server should host this?.

If it fails

Section titled “If it fails”
  • The node never appears. The agent tries enrollment five times (after 0, 20, 60, 180 and 300 seconds), then again every 30 minutes. To retry at once: sudo systemctl restart hyperion-agent. Follow it with journalctl -u hyperion-agent -f.
  • “invite token is invalid or already used”. Create a new invite on the master, put the token in invite_token under [enrollment] in /etc/hyperion/agent.toml and restart the agent. Do not delete /etc/hyperion/node-id.json: it is the node’s identity, and without it the node enrolls as a new node and its sites are orphaned.
  • The agent stops after you change the master’s certificate. The node refuses an unverified connection. Run journalctl -u hyperion-agent -g 'TLS policy' on the node for the fix.
  • Test connection fails. Check that port 9443 reaches the node from the master. See A node shows as unreachable. The Firewall page has a preset Worker RPC from the master only.
  • The auto-detected master URL is not reachable. If the page warns about a loopback or 0.0.0.0 address, fix Master URL the new node calls back to before creating the invite.

After you add a node

Section titled “After you add a node”