Build Your Own IM in 10 Minutes: JuggleIM Private Deployment in Practice

JuggleIM

Tutorial2026-07-15

If you want to add instant messaging to your product, you usually have to deal with a long list of complex issues: long connections, message storage, offline messages, group chat, friend relationships, push notifications, admin console, and more.

JuggleIM integrates all of this into a complete, privately deployable IM service. For individual developers, startup teams, or enterprises that need to quickly validate their business, all you need is a Linux server and a MySQL database to quickly run your own IM.

Even better, once the service is installed, it comes with a business server, web chat client, and admin console already integrated. You don't need to download a separate demo to register an account and start chatting.

Two Deployment Options: One-Click and Manual

JuggleIM supports both single-node and cluster editions. For development testing, small-scale business, or product validation, we recommend starting with the single-node edition.

The server is recommended to run a mainstream Linux system, with MySQL 8.x. The official recommended configuration is 4 cores / 8GB RAM; for actual test environments, you can also lower the spec depending on the load.

Option 1: One-Click Deployment

If you want to get up and running as quickly as possible, we recommend using the official installer.

First, download the installer on the server:

wget https://downloads.juggle.im/server/linux/amd64/juggleim.ctl

sudo chmod u+x juggleim.ctl

Create a private-cloud app in the JuggleIM website's developer console and generate an installation license, then run:

sudo ./juggleim.ctl install

The installer automatically completes service download, configuration, and startup, dramatically reducing manual operations.

The full steps are available at:

https://www.juggle.im/docs/guide/deploy/quickdeploy/

Option 2: Manual Deployment

If you want to control the install directory, config files, and startup process yourself, you can also choose manual deployment:

Download the latest installation package from the release page;
Extract the package;
Prepare the MySQL database;
Modify conf/config.yml;
Start imserver.

The latest version is always at the top of the release page. As of this article, the latest is v1.8.14.

Manual deployment guide:

https://www.juggle.im/docs/guide/deploy/manualdeploy/

Latest version and changelog:

https://www.juggle.im/docs/guide/deploy/releasenodes/

How Simple Is the Single-Node Configuration?

With the current single-node edition, the vast majority of config items can use defaults. The only thing you really need to fill in is the MySQL connection info:

clusterMod: single
msgStoreEngine: mysql

mysql:
   user: root
   password: your_password
   address: 127.0.0.1:3306
   name: im_db

If the database account and password have already been configured by the installer, what you usually need to pay attention to is just the database address and database name.

You need to create an empty database in advance, and make sure the configured account has the permissions to create tables, modify table structure, and read/write data.

When the service starts, it automatically runs database initialization and version migration, creating the data tables required for the current version. On subsequent version upgrades, the table structure is updated according to the built-in migration scripts, so you don't need to import full SQL manually every time.

This means starting an IM from scratch on a single node is basically just:

Prepare MySQL → fill in the connection info → start the service

Apply for a Free License and Create Your First App

JuggleIM is multi-tenant: a single private deployment can create multiple isolated Apps. Each App has its own AppKey, users, groups, conversations, and message data.

The license workflow is in two parts:

The website provides a free license that supports up to 100 registered users — ideal for development testing, small teams, and early product validation.

Note: the 100 here refers to registered users, not concurrent online users. If your business exceeds 100 registered users, you can contact the official team to ask about user-count add-on packs and the corresponding purchase options.

Port 8090: The Private Admin Console

Once the service is installed, access the admin console at:

http://server-IP:8090

The default credentials are:

Account: admin
Password: 123456

After the first login, we recommend changing the default password immediately, and avoid exposing the admin console directly to the public network.

The admin console mainly provides the following capabilities:

License import and App creation;
Management of AppKey, AppSecret, and other app info;
Set access aliases for Apps;
Query users, groups, conversations, and history messages;
User ban / unban and online status management;
Recall and delete history messages;
Statistics on message volume, registered users, active users, and connection count;
Service performance metrics and node-status monitoring;
Sensitive-word and message-interception rule management;
File storage, vendor push, audio/video, and callback configuration;
Admin accounts and permission management.

One very important step here is to set an alias for the newly created App.

AppKeys are usually quite long and not suitable for end users to enter directly. The App alias is a short identifier used externally for that App; the web client uses it to find the corresponding App and service configuration.

For example, you can set an App alias to:

Aliases must be unique. Once set, the web client just needs this alias on its first visit.

Port 9003: An Out-of-the-Box Web Chat Client

The current version of JuggleIM already packages the web client into the service, so you don't need to download front-end source code separately or deploy Nginx.

After installation, just visit in a browser:

http://server-IP:9003

Port 9003 serves both the web client entry and IM long-connection access, so it needs to be opened in the server's security group, firewall, or load balancer.

The first time you open the web client, the page will ask for the App alias. This is the alias you just set in the 8090 admin console.

After that, you'll see the registration or login page.

The web client already has a complete set of chat-product basics, including:

User registration and login;
User profile settings;
User search and friend management;
Single-chat messages;
Group creation and group-member management;
Group-chat messages;
Text, image, file, and other message types;
Conversation list and unread messages;
Message recall, delete, and read state;
Blacklist and personal settings;
Multi-device message sync.

For developers, this built-in web client is not only a product-experience entry point, but also a way to verify that service deployment, long connections, message send/receive, friend relationships, and group chat are all working correctly.

The Service Also Comes with a Business Server

Many IM services only provide the underlying messaging capability after deployment, leaving developers to implement registration, login, friend relationships, group management, and file upload as additional business interfaces.

JuggleIM's single-node edition already includes a built-in business server, integrated with the web client. Once the service is up, you can immediately experience the following:

Register an account → search and add a friend → start a single chat → create a group → invite members and send group messages

So during testing and product validation, there's no need to develop an additional business backend, and no need to integrate Android, iOS, or Web SDKs first. You can quickly confirm whether the entire IM chain meets expectations.

Once the business is officially live, you can integrate the client SDK, server API, message callbacks, and push services according to your product needs.

A Post-Deployment Checklist

After installation, follow these steps in order to verify:

Visit http://server-IP:8090 and confirm the admin console opens;
Change the default admin password;
Apply for a free license from the website's developer console;
In the private admin console, import the license and create the App;
Set a unique alias for the new App;
Visit http://server-IP:9003;
Enter the App alias;
Register two test accounts;
Add a friend and send a single-chat message;
Create a group and send a group-chat message.

If all these steps work normally, the database, business service, web client, and IM long connections are all running.

Final Words

Building your own IM service doesn't necessarily mean you have to reinvent the wheel starting from long connections and message protocols.

With JuggleIM, a single Linux server, a MySQL database, and a free license, you can quickly get:

A privately deployed IM service;
A complete business server;
An out-of-the-box web chat client;
A visual admin console;
Single chat, group chat, friends, conversations, and history messages;
A complete foundation for later mobile SDK and server API integration.

If your registered users are under 100, you can apply for a free license directly. If you exceed the free quota, you can contact the official team to ask about user-count add-on packs.

One-click deployment: