JuggleIM

A high-performance, scalable open-source instant messaging (IM) system.

简体中文 | English

Website · Docs · Quick Deploy · API Reference · Ask a Question

If this project helps you, please give it a ⭐ Star — it keeps the project easy to find and motivates us to keep building!

📖 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

🧬 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:

defaultPort: 9003       # im-server default listening port
nodeName: testNode      # node name
nodeHost: 127.0.0.1     # node IP
msgStoreEngine: mysql   # message store engine: mysql (default) or mongo

log:
  logPath: ./logs       # runtime log directory
  logName: jim-info     # runtime log filename prefix
  visual: false         # enable visual logs (write to a KV store, queryable in the admin console)

mysql:                  # MySQL configuration
  user: root
  password: 123456
  address: 127.0.0.1:3306
  name: im_db

# mongodb:              # MongoDB config, active when msgStoreEngine is "mongo"
#   address: 127.0.0.1:27017
#   name: jim_msgs

apiGateway:             # server-side API port for business app servers
  httpPort: 9001

navGateway:             # navigator endpoint used by client SDKs
  httpPort: 9002

connectManager:         # WebSocket long-connection port
  wsPort: 9003

adminGateway:           # built-in admin console, default credentials admin/123456
  httpPort: 8090

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.

Name		Name	Last commit message	Last commit date
Latest commit History 666 Commits
.github		.github
cmd/jimbench		cmd/jimbench
commons		commons
docker/mysql-init		docker/mysql-init
docs		docs
examples		examples
launcher		launcher
scripts		scripts
services		services
simulator		simulator
sql		sql
testmain		testmain
.dockerignore		.dockerignore
.gitignore		.gitignore
BENCHMARKS.md		BENCHMARKS.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

JuggleIM

📖 What is JuggleIM

✨ Key Features

🗂 Table of Contents

🧬 Ecosystem

🏗 Architecture

🚀 Quick Start with Docker

🛠 Manual Deployment

1. Install and Initialize MySQL

2. Install MongoDB (optional)

3. Start im-server

4. Configure Public Access Addresses

🏢 Create an Application (Tenant)

🔌 Business Server / Client Integration

💬 Community

🤝 Contributing

⭐ Star History

📄 License

About

Uh oh!

Releases 2

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

JuggleIM

📖 What is JuggleIM

✨ Key Features

🗂 Table of Contents

🧬 Ecosystem

🏗 Architecture

🚀 Quick Start with Docker

🛠 Manual Deployment

1. Install and Initialize MySQL

2. Install MongoDB (optional)

3. Start im-server

4. Configure Public Access Addresses

🏢 Create an Application (Tenant)

🔌 Business Server / Client Integration

💬 Community

🤝 Contributing

⭐ Star History

📄 License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages