Linux

Choose a package manager, initialize a single-node cluster, and verify readiness and Manager access.

Install a single-node cluster with APT or DNF, then start it with systemd. Current preview: v3.0.0-beta.24 · amd64/x86_64.

Preview is a prerelease channel

Validate it outside production before serving production traffic.

Supported distributions and architecture

The preview repository supports amd64/x86_64. It is verified on Ubuntu 24.04, Debian 13, Rocky Linux 9, and AlmaLinux 9; RHEL 9 can use the same EL9 repository.

1. Install

Choose your distribution and expand its commands.

Debian / Ubuntu

APT installation commands

curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo apt update
sudo apt install -y wukongim

RHEL / Rocky / AlmaLinux 9

DNF installation commands

curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo dnf -y --disablerepo='*' --enablerepo=wukongim-preview makecache --refresh
sudo dnf install -y wukongim

Expected: wukongim and wkcli have matching version, commit, and build_source; the service has not started yet.

Verify binary identities and installation paths

The same package installs the server and the unified operator CLI. Their version, commit, and build_source fields must match. See wkcli for command usage. If wkcli is missing or its identity differs, check command -v wkcli for an older binary on PATH and update to the matching package.

wukongim version --output json
wkcli version --output json

The package creates the service account, systemd service, /etc/wukongim, /var/lib/wukongim, and /var/log/wukongim. It does not create a configuration or start the service.

2. Initialize the configuration

Run sudo wukongim init, save the password shown only once, then validate the config. Listeners use loopback by default; configure the firewall, TLS, and ingress before exposing them.

Expected: /etc/wukongim/wukongim.toml exists and configuration validation succeeds.

Initialize, validate, automate, and forward Demo ports

sudo wukongim init
# For automation:
sudo wukongim init \
  --admin-password-stdin < /secure/path/manager-password

Save the administrator password, which is shown only once. Existing automation may keep using wukongim config init --config /etc/wukongim/wukongim.toml. Then validate the configuration:

sudo wukongim config validate --config /etc/wukongim/wukongim.toml

Services bind to loopback by default. Configure the firewall, TLS, and ingress policy before exposing them.

Initialization binds WebSocket to 127.0.0.1:5200, which /route preserves as a concrete listener address. Forward 5001, 5200, and 5301 as shown in Quick Start to use the Demo without api.external_ws_addr. If the listener is changed to a wildcard, default external routing can complete its host from the request. Remapped external ports, separate domains, and TLS proxies still require explicit published addresses; see the Docker address rules.

3. Start and verify

Start the systemd service and check /readyz. Admit traffic only after 200 with ready: true; inspect service logs if the check fails.

Start, check readiness, and inspect logs

sudo systemctl enable --now wukongim
curl --fail http://127.0.0.1:5001/readyz

Add the node to traffic only after /readyz succeeds. If startup fails, inspect the logs:

sudo journalctl -u wukongim -n 100 --no-pager

Open Manager: create an SSH tunnel from your computer, then visit 127.0.0.1:5301. Sign in as admin with the saved password. Keep auth_on = true; port 5301 needs no public access.

SSH tunnel and shared administration

The default Manager address is http://127.0.0.1:5301. Sign in as admin with the password saved during initialization and keep auth_on = true. For remote access, run the following on your computer, keep the terminal open, and open the same browser address:

ssh -N -L 127.0.0.1:5301:127.0.0.1:5301 <user>@<server-ip>

Port 5301 does not need a public firewall rule. For shared administration, use a management network or VPN with an HTTPS proxy; see Manager.

Configure client addresses

Connect through domains, TLS, or remapped ports.

Deploy multiple nodes

Start with three servers for replication and recovery.

For multiple nodes, continue to Multi-node Cluster. Before upgrading, read Upgrade & Migration.