im-server

---

What is JuggleIM

JuggleIM is a ready-to-use, self-hostable instant messaging (IM) backend. Built on a Protobuf + WebSocket long-connection protocol, it focuses on efficient message delivery and reliable storage, letting you add chat capabilities to your app, website, or business system in minutes.

Whether you are building a social product, a customer-service system, IoT device communication, live-stream chat, or AI bot conversations, JuggleIM serves as a solid messaging foundation. It is multi-tenant by design — a single deployment can host multiple fully isolated applications — and the professional edition scales horizontally to support hundreds of millions of daily active users.

Want to try it right away? Jump to the Docker Quick Start below.

✨ Key Features

** High Performance & High Availability**

• Protobuf + WebSocket long connections — low bandwidth, high throughput, and reliable connectivity even on poor networks
• Professional edition supports clustered deployment with unlimited horizontal scaling, powering apps with hundreds of millions of DAU
• Handles large groups of 10,000–100,000 members without losing messages, plus unlimited-size live chat rooms

** Secure & Reliable**

• Tenant-scoped credentials and token-based client authentication, with HTTPS/WSS recommended for production transport security
• Multi-device online presence and message sync keep state consistent across all endpoints

** Flexible Deployment & Global Reach**

• Supports public cloud, private cloud, and managed cloud deployment models
• Global link acceleration for worldwide-scale applications

** Easy to Integrate & Extend**

• SDKs for Android, iOS, Web, PC, Flutter, and HarmonyOS, each with a demo and docs
• Rich REST APIs and WebHooks for integrating with your existing systems
• Built-in AI bot connectivity — easily plug in large language models
• Comes with ops tooling and an admin console for simple maintenance

Table of Contents

• Ecosystem
• Architecture
• Quick Start with Docker
• Manual Deployment
• Create an Application (Tenant)
• Integration
• Community
• Star History

Ecosystem

JuggleIM follows a layered architecture — "core service + business service + multi-platform SDKs + demos" — with clearly separated repositories that can be composed and customized as needed.

Repository Description im-server Core IM service handling message delivery, storage, and related IM logic (this repo) jugglechat-server Demo business service handling user registration/login, group creation, friends, etc. — a base for your own development jugglechat-server-java Java version of the demo business service imserver-console Admin console for IM configuration and business metrics imsdk-android Android imsdk with a UI demo, ready for customization imsdk-ios iOS imsdk with a UI demo, ready for customization imsdk-web Web imsdk imsdk-flutter Flutter version of imsdk imsdk-harmony HarmonyOS imsdk with a UI demo, ready for customization jugglechat-web Web demo integrating imsdk-web, ready for customization jugglechat-desktop Desktop demo integrating imsdk-pc, ready for customization jugglelive-web Live chat-room demo integrating imsdk-web, ready for customization bot-connector Bot connector service bridging im-server and third-party bots imserver-sdk-go SDK wrapping the im-server server-side API for easy integration imserver-sdk-java Java version of imserver-sdk

The desktop imsdk-pc is not yet open-sourced — contact support for details.

Architecture

JuggleIM runs as a modular Go service: HTTP and WebSocket gateways route requests through an internal actor/RPC runtime to messaging, identity, conversation, history, push, file, bot, and RTC modules. Read the architecture guide for component boundaries, data ownership, private and group message flows, security boundaries, and deployment constraints. 简体中文版

Evaluate performance with the reproducible benchmark harness, which reports connection setup separately from private-chat and group-chat ACK and delivery throughput, including P50/P95/P99 latency and machine-readable results.

Quick Start with Docker

Run a complete local JuggleIM stack with MySQL and the admin console:

git clone https://github.com/juggleim/im-server.git
cd im-server
docker compose up -d

Once the containers are healthy, the local services are available at:

Service Address Purpose Server API http://127.0.0.1:9001 Called by your business server Navigator http://127.0.0.1:9002 Returns the client connection address WebSocket ws://127.0.0.1:9003 Used by client SDKs for long connections Admin console http://127.0.0.1:8090 Manage applications; default login: admin / 123456

Create a local application, register two synthetic users, and send a private message with the verified server API example:

bash examples/server-api-quickstart.sh

The script keeps the generated application secret on the server side and prints the two temporary user tokens needed for local SDK testing. See the server API quick start for the complete flow and security boundaries. 简体中文版

Stop the local stack with docker compose down. To remove its MySQL data as well, use docker compose down -v.

If the stack does not become healthy, follow the Docker Compose troubleshooting guide for status checks, logs, port conflicts, MySQL health, and safe reset steps. 简体中文版

For production, clustering, and managed deployment options, see the Deployment Guide.

Manual Deployment

Click to expand the full manual deployment steps

1. Install and Initialize MySQL

Create the database schema:

CREATE SCHEMA `jim_db`;

Initialize the table structure (the SQL file lives at sql/imserver.sql):

mysql -u{db_user} -p{db_password} jim_db < sql/imserver.sql

2. Install MongoDB (optional)

Only required when using MongoDB to store message data (msgStoreEngine: mongo).

3. Start im-server

The working directory is im-server/launcher, where conf holds config files and logs is the runtime log directory.

Edit the config file im-server/launcher/conf/config.yml:

…

Start the service from the im-server/launcher directory:

go run main.go

4. Configure Public Access Addresses

Ports that need to be exposed:

Port Protocol Description 9001 http Server-side API port, called by business servers (e.g. jugglechat-server) 9002 http Navigator port, used to discover the WebSocket connection address 9003 websocket IM long-connection port for client SDKs 8090 http Admin console port, default credentials admin/123456

Configure exposure however suits your environment (public IP, Nginx reverse proxy, load balancer, etc.). For local testing, an intranet IP is enough.

Register the long-connection address by inserting a config row into the database:

insert into globalconfs (conf_key, conf_value) values ('connect_address', '{"default":["127.0.0.1:9003"]}');

Replace 127.0.0.1 with your machine's intranet IP or public IP/domain. This address is delivered to client SDKs by the navigator service.

Create an Application (Tenant)

JuggleIM is a multi-tenant system — a single deployment can host multiple appkeys (tenants) with fully isolated data.

Create a tenant via the admin API (app_key is the tenant identifier and must be unique):

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

Example response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "app_name": "appname",
        "app_key": "appkey",
        "app_secret": "hciKcc6sXRDjYUQp"
    }
}

You can also log in to the admin console at http://127.0.0.1:8090 (default credentials admin/123456) to view and manage your applications.

Business Server / Client Integration

1) Business Server Integration

Item Example Notes IM server-side API address http://127.0.0.1:9001 Used by your business server to call IM APIs (register users, create groups, send system messages, etc.). See the API Reference app_key appkey1 Tenant identifier, unique within the system app_secret hciKcc6sXRDjYUQp Auth secret generated on app creation (must be 16 chars if custom). Use only on the business server — never expose it to clients

2) Client SDK Integration

Item Example Notes IM connection address ws://127.0.0.1:9003 Passed to the client SDK on init. See Quick Start app_key appkey1 Must match the value used on the business server

Community

Interested in IM or have integration questions? Join the community and let's chat

• Telegram Group (Chinese)
• GitHub Discussions for questions, ideas, and project showcases
• GitHub Issues for reproducible bugs and scoped feature requests

Contributing

Contributions of all kinds are welcome! You can:

• Open an Issue to report bugs or request features
• Submit a Pull Request to improve the code or docs
• Share the projects you build on top of JuggleIM

⭐ Star History

If JuggleIM has helped you, please give us a Star — your support drives our continued development!

License

This project is released under the LICENSE.