JuggleIM im-server: a self-hosted Go IM backend you run with Docker Compose

The gap im-server fills: chat state you own, not chat state you rent

Most teams that add chat to a product end up choosing between a hosted messaging API and writing a message pipeline themselves. The hosted route puts conversation history, delivery receipts and group membership on someone else's infrastructure. The build-it-yourself route means designing a long-connection protocol, a message store, offline push, multi-device sync and group fan-out before the first message is ever delivered. JuggleIM im-server is aimed at the second group. It is the core IM service in a larger set of repositories: message delivery, storage and the IM-specific logic live here, while user registration, login, group creation and friends live in a separate business service such as jugglechat-server. That split is the first thing to understand, because it defines what you are adopting. You are adopting a messaging engine with a documented HTTP and WebSocket surface, not an application. The repository description names the intended audience directly: private chat, groups, chatrooms, WebSocket and REST APIs, self-hosted. The README adds multi-tenancy, meaning one deployment can host several isolated applications, and lists social products, customer service, IoT device communication, live-stream chat and AI bot conversations as target uses. If your requirement is a chat panel embedded in a website with no server of your own, this is the wrong shape of tool.

Inside the Go service: gateways, an actor runtime, and modules behind them

The README describes the architecture as a modular Go service in which HTTP and WebSocket gateways route requests through an internal actor/RPC runtime to messaging, identity, conversation, history, push, file, bot and RTC modules. That is the data flow to keep in mind when sizing a deployment: client traffic enters over one of two transports, and the modules behind the runtime are where state and storage live. The client protocol is Protobuf over WebSocket long connections, which the README frames as low bandwidth and reliable on poor networks. The repository layout matches the description. cmd/ and launcher/ hold entry points, services/ holds the service modules, commons/ holds shared code, sql/ holds the schema, and simulator/ exists alongside examples/. The go.mod file confirms the storage and transport choices rather than leaving them implied: go.mongodb.org/mongo-driver and github.com/syndtr/goleveldb appear as dependencies, as do go-zero for the HTTP layer, google.golang.org/protobuf, and cloud storage SDKs for Aliyun OSS, AWS, MinIO and Qiniu. The docker-compose.yml sets MSG_STORE_ENGINE to mysql, so MySQL is the default message store in that stack even though the module graph carries other engines. The architecture guide at docs/architecture.md is where the repository says component boundaries, data ownership, private and group message flows, security boundaries and deployment constraints are documented. That file, not the README, is the place to look before you decide how many processes you need.

Running im-server locally with docker compose up

The repository ships a one-command local stack. The docker-compose.yml header states that running the compose file brings up the IM WebSocket endpoint on ws://127.0.0.1:9003, the server-side API on http://127.0.0.1:9001, and an admin console on http://127.0.0.1:8090 with the credentials admin / 123456. The compose file also documents that the MySQL root password can be overridden by exporting MYSQL_ROOT_PASSWORD before bringing the stack up. The command is:

docker compose up -d

The stack contains a mysql:8.0 service named juggleim-mysql, configured with the database jim_db and utf8mb4, and an im-server service built from the repository Dockerfile. The MySQL service mounts ./sql/imserver.sql as an init script, and a comment in the compose file notes that the schema is created on first init while auto-migration tops it up on startup. The im-server container waits for the MySQL health check before starting. Environment variables in the compose file include POD_NAME set to jim-node-1, POD_IP set to 127.0.0.1, MSG_STORE_ENGINE set to mysql, MYSQL_ADDR set to mysql, and MYSQL_ROOT_PASSWORD defaulting to juggleim. Once the stack is up, the compose header gives the tenant creation call:

curl -X POST http://127.0.0.1:8090/admingateway/apps/create \
     --data '{"app_key":"appkey","app_name":"appname"}'

That returns the application you will point clients at. For server-side integration, the repository includes examples/server-api-quickstart.sh, and the ecosystem table lists imserver-sdk-go and imserver-sdk-java as wrappers around the server-side API, so a first real use is usually a shell or SDK script that creates a tenant and then sends a message through the REST API rather than hand-writing HTTP calls. The Dockerfile exposes ports 9003, 9001, 9002 and 8090, plus 6060 for pprof, and its entrypoint renders config_template.yaml from environment variables before launching the binary. The README does not document rollback or downgrade steps for the schema, so treat the first migration as one-way until you have read the SQL yourself.

Where im-server stops and your business service has to start

The ecosystem table is explicit that user registration and login, group creation and friends belong to a demo business service, not to this repository. If you deploy only im-server, you have a messaging engine with tenant-scoped credentials and token-based client authentication, and you do not have a signup flow. That is a real integration cost, and it is the most common place teams misjudge the work. The README also notes that the desktop imsdk-pc is not open-sourced and that support must be contacted for it, so a desktop client is not something you can simply clone from the ecosystem list. The scaling claim needs reading with the same care. The README says the professional edition supports clustered deployment with unlimited horizontal scaling and can power apps with hundreds of millions of daily active users. It does not say the open-source edition does. Nothing in the repository states which clustering features fall on which side of that line, so anyone planning a multi-node production deployment should confirm it before designing around it. The same caution applies to the performance figures: the README points to BENCHMARKS.md as a reproducible harness that reports connection setup separately from private-chat and group-chat ACK and delivery throughput, with P50, P95 and P99 latency and machine-readable results. That is a harness you run on your own hardware, not a number to copy from a page.

im-server against a hosted messaging API, and against building your own pipeline

The obvious alternative for a team that does not want to operate a message store is a hosted chat API, the model where a vendor runs the connection layer and the history database and you pay per monthly active user. The difference in approach is where the data lives and who carries the on-call rotation. A hosted API removes MySQL, the schema migration, the push configuration and the connection scaling from your plate entirely; im-server hands all of that back to you in exchange for control of the message store and no per-user ceiling set by a vendor. The second alternative is writing the pipeline yourself on top of something like a raw WebSocket library and your existing database. That path gives you exactly the protocol and schema you want, and it means you own group fan-out, offline push, multi-device sync and history queries, which is most of what the services/ directory in this repository exists to do. im-server is the middle option: more control than a hosted API, less invention than a from-scratch build, and a Go module you can read. On the client side the ecosystem offers SDKs for Android, iOS, Web, PC, Flutter and HarmonyOS, each with a demo, which is the practical argument for the middle option if you need several platforms and do not want to write a protocol client six times.

Licence, releases and what upgrading actually costs

The repository is Apache-2.0, and the LICENSE file sits at the top level. Apache-2.0 is a permissive licence with an explicit patent grant, and it does not require you to publish modifications. It also does not grant trademark rights, so shipping a product under the JuggleIM name is a separate question from shipping the code. This is a description of the licence text, not legal advice; if the multi-tenant deployment model matters commercially, have counsel read the LICENSE file and the terms around the professional edition, because the README presents the open-source repository and a commercial edition as different things. On maintenance, the last push to the default branch was on 2026-09-09, and the most recent releases listed are v1.8.16 on 2026-08-24, v1.8.14 on 2026-07-15 and v1.8.12 on 2026-07-03. That is a steady release cadence over the period shown. The upgrade cost is dominated by the database. The compose file's own comment says the schema is created on first init and auto-migration (Upgrade()) tops it up on startup, which means the binary will alter your schema when it starts against an older database. Versioned SQL under sql/ is what you diff before an upgrade, and the schema is what you back up before one. The Go toolchain is pinned in go.mod at go 1.25.12, and the Dockerfile builds from golang:1.25.12-alpine, so a build from source needs that toolchain or newer.

Editorial conclusion

Adopt im-server if you need to own the message store and already run MySQL 8.0, and if your client work can absorb a Protobuf WebSocket protocol plus a separate business service for registration and friends. Skip it if you want a hosted chat widget or a single binary with no database, because this repository is the core service only and its own README splits user registration, group creation and friend logic into a different repository. Before committing, check the docker-compose.yml environment block against your own deployment, confirm whether the clustering and horizontal scaling described in the README sit in the professional edition or the open-source one, and read docs/architecture.md for the component boundaries.

Frequently asked questions

Official sources

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