Linux

The Linux path fits teams that want direct control over hosts, filesystems, networking, and service lifecycle. The repository can now build deb/rpm preview packages, and the separate WuKongIM/packages repository has a fail-closed bootstrap at the verified HTTPS endpoint packages.githubim.com. Signing keys and APT/YUM indexes are not enabled yet, however, so that endpoint cannot be used for installation. Do not treat these local previews as a signed production distribution channel.

The first preview targets Linux amd64 and runs installation contract checks on Ubuntu 24.04, Debian 12, Rocky Linux 9, and AlmaLinux 9.

1. Build and install a local preview package

The repository requires Go 1.25.11; the package configuration is validated with GoReleaser v2.18.0:

git rev-parse HEAD
go version
goreleaser release --snapshot --clean \
  --config .goreleaser.packages.yaml
(cd dist && sha256sum --check checksums.txt)

Install the generated .deb on Debian or Ubuntu:

sudo apt install ./dist/wukongim_*_linux_amd64.deb

Install the generated .rpm on Rocky or AlmaLinux:

sudo dnf install ./dist/wukongim_*_linux_amd64.rpm

The package installs /usr/bin/wukongim and a hardened wukongim.service, then creates the wukongim system account and /etc/wukongim, /var/lib/wukongim, /var/log/wukongim, and /run/wukongim. It does not create an active configuration, enable or start the service, or restart it.

Confirm the binary identity:

wukongim version
wukongim version --output json

2. Initialize a secure configuration

Interactive initialization creates a single-node cluster configuration with a random Cluster ID, join token, Manager JWT secret, and administrator password. The generated administrator password is shown only once:

sudo wukongim config init \
  --config /etc/wukongim/wukongim.toml

Automation must supply an administrator password of at least 12 characters through standard input; the command does not echo it:

sudo wukongim config init \
  --config /etc/wukongim/wukongim.toml \
  --admin-password-stdin < /secure/path/manager-password

Initialization binds TCP, WebSocket, API, Manager, and node transport to loopback by default. Add --gateway-public during first initialization only after the host firewall, TLS termination, and ingress policy are ready. That option exposes only the client TCP/WebSocket Gateway on all interfaces; it does not expose Manager or node transport.

The generator refuses to overwrite an existing file and applies the same configuration validation as service startup before atomically publishing it. When run as root with the wukongim group present, it writes root:wukongim 0640; otherwise it uses 0600. Review advertised addresses, node identity, mounts, and network policy, then validate explicitly:

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

Configuration errors return exit code 78. The systemd unit includes that code in RestartPreventExitStatus so invalid configuration cannot create a restart storm. The loader also rejects unknown TOML keys and unknown WK_* environment variables.

3. Start and verify

sudo systemctl enable --now wukongim
sudo systemctl status wukongim
sudo journalctl -u wukongim -n 100 --no-pager

curl --fail http://127.0.0.1:5001/readyz

On SIGTERM, the process performs a graceful shutdown using the configured cluster stop budget; the unit provides a 30-second external ceiling. If /healthz succeeds while /readyz returns 503, do not add the node to the load balancer. Inspect the response reason and service logs first.

Also verify persistent mounts, directory ownership, and advertised addresses from the target client network, then recheck /readyz after a service restart.

Package lifecycle

• Installation creates no active configuration and does not enable or start the service.
• Upgrade replaces package files but does not automatically restart a running node. Validate compatibility and configuration, then restart explicitly during a planned window.
• Removal stops and disables the service but preserves configuration, data, logs, and the service account.
• The service process applies the same configuration validation before constructing runtimes. Configuration errors exit with 78 and are not restarted. The unit permits writes only to package-managed state, log, and runtime directories.

Before an upgrade, validate the target commit, artifact, configuration, backup, and recovery path outside production. Roll one node at a time only when the target release explicitly supports mixed operation with the current version; otherwise use a full maintenance window. See Upgrade & Migration for the complete boundary.

Install from source

Until the public repository is enabled, you can also build the binary directly:

GOWORK=off go build -trimpath -o ./bin/wukongim ./cmd/wukongim
sha256sum ./bin/wukongim

A source deployment should still reuse packaging/systemd/wukongim.service, the repository sysusers/tmpfiles definitions, and the secure initialization command. Do not build separately from a moving branch on every production node, and do not copy the root development example directly into an active production configuration.

For multi-node configuration, continue to Multi-node Cluster.