WuKongIM v3 beta: a self-hosted messaging server that ships its own storage

The part of chat you should not be writing yourself

Most teams building a chat feature start with a broker and a database, then discover that the hard part was never transport. It is ordering within a channel, replaying what a user missed while offline, and keeping several devices for the same account in agreement about what has been read. WuKongIM takes that layer and packages it as a server. The README describes it as handling message storage, synchronization, presence and online delivery, while your application supplies the user interface, the account system and the business rules. That division is the whole pitch. You are not adopting a chat product with its own login screen and contact list. You are adopting the server half and keeping the product half. The intended audience is a backend team that already has identity and permissions and now needs delivery guarantees, not a team looking for a drop-in messenger widget.

Channels, slots and why there is no external database in the diagram

The design choice that shapes everything else is that message, metadata and replication storage are built in. The README states the core needs no external database, cache or message queue. That removes a class of operational work: no connection pool to size, no cache invalidation to reason about, no broker to upgrade on a different schedule from the application. Messages live under /var/lib/wukongim on the Linux package install. The cluster model is deliberately uniform. You start with a single-node cluster and use the same messaging model when you add nodes, with 256 hash slots by default. A channel is the unit of ordering and the unit of placement, and the slot count is the knob that decides how channels are distributed. Because the single-node case is still a cluster, the migration path is a matter of adding members rather than rewriting how the application addresses channels. Channel types cover personal, group and custom, which is what lets application notifications ride the same ordering guarantees as user conversation instead of a separate path.

Installing on Linux and proving two users can talk

The documented quick start targets amd64/x86_64 on Ubuntu 24.04, Debian 13, Rocky Linux 9, AlmaLinux 9 and RHEL 9, and requires systemd, sudo, curl and SSH. No Go toolchain is needed. On Ubuntu or Debian the repository is added with curl -fsSL https://packages.githubim.com/repo | sudo sh, followed by sudo apt update and sudo apt install -y wukongim. The RHEL family uses the same repository script and then sudo dnf install -y wukongim. Confirm what you got with wukongim version. Initialization is sudo wukongim init, and the configuration is validated with sudo wukongim config validate --config /etc/wukongim/wukongim.toml. The Manager administrator password printed during init is shown once, so capture it then. Readiness is a polled endpoint: curl --retry 30 --retry-delay 2 --retry-all-errors --max-time 5 --fail http://127.0.0.1:5001/readyz, and you wait for {"ready":true}. The generated configuration binds services to loopback, so a remote server needs SSH forwarding of ports 5001, 5200 and 5301 before the Demo and Manager are reachable from your machine. The Demo itself uses two fixed test identities, quickstart-alice and quickstart-bob, with the tokens alice-local-token and bob-local-token, and the README is explicit that this token registration through /user/token is a demo affordance: a trusted backend must own identity checks and token issuance in a real deployment.

The beta label is not decorative

The README carries a note that v3 is in beta, that the Linux quick start draws from a Preview package repository, and that APIs, configuration and durable formats may change. The release list bears that out: v3.0.0-beta.9, beta.12 and beta.13 arrive within days of each other in September 2026, and beta.12 to beta.13 is the same day. A durable format that may change is the expensive kind of churn, because it is the one that touches stored messages rather than source code. The README points to an upgrade and migration page and asks you to review it before changing versions, which is the correct instruction and also a warning. There is a second, smaller trap in the same area: the English UI and the ?lang=en parameter are described as present in the current development build, and older packages and the hosted demo may still render Chinese. If your evaluation depends on the English interface, verify the build you installed rather than the screenshots.

When a broker plus a database is the better shape

The obvious alternative is building on a general-purpose message broker and a database you already operate, for example a log-based broker for transport plus a relational store for history. The difference is not performance, it is where the semantics live. With a broker you get a stream and you write the parts that make it a chat system: the per-channel sequence, the offline cursor per device, the read state, the fan-out to group members. WuKongIM moves all of that into the server and asks you to accept its channel and slot model in exchange. That trade is bad if your organization already has deep operational practice around a broker and a database, because you would be adding a second stateful system whose storage you cannot inspect with the tools you already know. It is good if the alternative is one engineer inventing an offline sync protocol over a weekend. The decision hinges on whether per-channel ordering and multi-device session state are core to your product or incidental to it.

What you are taking on at upgrade time

The material supports a few concrete observations about maintenance cost. The project is written in Go and licensed Apache-2.0, which permits commercial use and modification, but the licence text itself is the authority and this is not legal advice. Because storage is embedded, backup and restore are your responsibility against the data directory rather than a managed database service, and the README lists backup tools among the included utilities without detailing them. The cluster default of 256 hash slots is set at initialization, so the slot count is a decision made early with consequences for how channels distribute later. Upgrades are where the beta status bites: the release cadence is fast, the durable format is explicitly in flux, and the documented answer is to read the migration guidance before changing versions. Budget for a staging node that receives each beta first and for the possibility that a rollback is not a simple binary swap. Teams that cannot schedule that kind of rehearsal should treat v3 as a system to evaluate rather than to depend on.

Editorial conclusion

Adopt WuKongIM if you are building a product that needs per-channel ordering, offline sync and multi-device sessions, and you would rather run one Go service than assemble a broker, a cache and a database. Stay away if you need a stable durable format today: the README states that APIs, configuration and durable formats may change in v3 beta, and the current release train is v3.0.0-beta.13. Before committing, verify three things on your own hardware. Run wukongim version after install to confirm which build the package repository actually delivered, check that /etc/wukongim/wukongim.toml exposes the cluster and slot settings you need, and read the upgrade and migration page for the durable format before you write a single message.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. WuKongIM/WuKongIM on GitHub