Manage Multi-Host Nginx with Cluster

Recommended approach

When you want to manage nginx on multiple hosts from a single Nginx UI dashboard, use the cluster Node feature instead of host SSH mode.

When to use what

Need	host_via_ssh	cluster Node
Container on host A managing nginx on host A	✓	✓ (overkill)
Container on host A managing nginx on host B	✗	✓
One Web UI viewing configs/logs across hosts	No	✓
Per-host autonomy if peer unreachable	No	✓

Recommended topology

Layer	Role	Notes
Browser	Opens the lead Nginx UI instance	Use one dashboard for daily operation
Lead node	Registers peer nodes and provides the node switcher	Can also manage its own local nginx
Peer nodes	Run their own Nginx UI instance	Each peer manages nginx on the same host
Cluster federation	Connects the lead node to peers	Requests run on the selected node

The lead node does not SSH into other hosts. It forwards operations through the cluster node connection. If a node runs Nginx UI in Docker and manages nginx installed on the same host, configure Manage Host Nginx from Docker on that node only.

Setup

1. Install nginx-ui on every host

Use the same deployment type on every node when possible. For a native Linux installation, run:

bash -c "$(curl -L https://cloud.nginxui.com/install.sh)" @ install

Docker deployments are also supported. See Install Script and Getting Started for the available installation methods.

2. Generate a Node Secret on each peer

Log into the peer's Web UI, go to Settings → Node, copy the Node Secret.

3. Register peers on the lead node

Configure peer nodes from app.ini or Docker environment variables:

app.ini

[cluster]
Node = http://10.0.0.2:9000?name=host-b&node_secret=<host-b-secret>&enabled=true
Node = http://10.0.0.3:9000?name=host-c&node_secret=<host-c-secret>&enabled=true

docker-compose.yml

services:
  nginx-ui:
    environment:
      - NGINX_UI_CLUSTER_NODE=http://10.0.0.2:9000?name=host-b&node_secret=...&enabled=true,http://10.0.0.3:9000?name=host-c&node_secret=...&enabled=true

4. Switch nodes from the Web UI

The node switcher in the top bar routes all subsequent operations to the selected node. Each operation happens locally on that node. There is no SSH connection between hosts.

DNS-01 certificates for peers

The DNS-01 plugin only needs to be installed on the lead node. With a peer selected in the node switcher, the certificate dialog of the site editor offers DNS Validation: On the main node, which is the default. The lead node then:

• validates the domain with its own DNS credentials, which never leave it;
• sends the certificate to the peer, where the site loads it;
• renews the certificate and sends every renewal to the peer.

On the lead node these certificates appear in the certificate list tagged For <node>. Deleting one stops its renewal. The files on the peer stay unless you choose to remove them as well, and they are kept when a configuration of the peer still loads them.

Choose On this node to validate with the plugin and the DNS credentials of the peer itself. Signed in on a peer directly, only that is available, and the dialog asks to install the plugin when it is missing. The peer has to run a release that can receive these certificates.

Combining cluster + host_via_ssh

You can have each cluster peer run host_via_ssh internally. In that layout, the container manages nginx on its own host, and cluster federation handles cross-host coordination.

See also:

• Cluster configuration reference
• Manage Host Nginx from Docker