Linux

The preview repository currently publishes v3.0.0-beta.21 for 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.

Preview is a prerelease channel

Validate it outside production before serving production traffic.

1. Install

Debian / Ubuntu

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

RHEL / Rocky / AlmaLinux 9

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

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

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

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

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.

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