JuggleIM Manual Deployment Guide

1. Introduction

JuggleIM itself provides a one-click installation and deployment tool. With this tool, even people who aren't very familiar with servers can quickly deploy a JuggleIM cluster. (One-click deployment guide: https://juggle.im/docs/guide/deploy/quickdeploy/)

Here, we introduce the manual deployment method for JuggleIM, to handle some special scenarios.

2. JuggleIM Deployment Architecture

Note: The red parts in the diagram are optional and can be flexibly selected based on your actual scenario.

3. JuggleIM Manual Deployment

1. Environment Preparation

• Server configuration: JuggleIM has no hard requirement on server configuration, but we recommend a 4C8G machine.
• Operating system: Any mainstream Linux distribution will do, such as CentOS, Ubuntu, etc.
• Network: A public IP is required (unless used in a pure intranet environment), and the relevant access ports must be opened.

2. Download the Installation Package

Download URL: https://juggle.im/docs/guide/deploy/releasenodes/

# Download the installation package
wget https://downloads.juggle.im/server/linux/amd64/juggleim-1.8.0.tar.gz
# Extract
tar -xvf juggleim-1.8.0.tar.gz

Directory structure:

• /conf Configuration files directory, which contains a sample configuration file;
• /imserver JuggleIM executable;
• /sql MySQL initialization scripts;
• /logs Log output directory;

3. Install Dependent Middleware

MySQL (required)

• 8.x or above is fine;
• Installation steps are omitted;
• Use the scripts in the sql directory of the deployment package to initialize the database.

MongoDB (optional)

• Omitted

HBase (optional)

• Omitted

Zookeeper (optional)

• Omitted

4. Configuration File

The conf directory of the deployment package contains a sample configuration file: config_example.yml. When actually using it, rename it to config.yml and modify the configuration items accordingly.

# IM cluster name
clusterName: jim_cluster

# IM node name; must be unique within the cluster
nodeName: jim_node

# Deployment mode: single / cluster
clusterMod: single

# Internal IP and RPC listening port of this node
nodeHost: 127.0.0.1
nodePort: 8888

# Message data storage engine. Options: mysql / mongo / hbase
msgStoreEngine: mysql

# In cluster mode, Zookeeper is required for node registration and discovery. Can be ignored in single-node mode.
zookeeper:
  address: 127.0.0.1:2181

# Log output directory
log:
  logPath: ./logs
  logName: im-server

# (Optional) Built-in time-series database for temporary storage of visualized logs, statistics, etc.
kvdb:
  isOpen: true
  dataPath: ./kvdb_data

# MySQL configuration
mysql:
  user: db_user
  password: db_pwd
  address: mysql_host:3306
  name: jim_db

# (Optional) MongoDB configuration. Required when msgStoreEngine is mongo.
mongodb:
  address: mongodb_host:27017
  name: db_name

# (Optional) HBase configuration. Required when msgStoreEngine is hbase.
hbase:
  address: hbase_host:2181

# IM long-connection (websocket) listening ports. 9002 is for internal use; 9003 is for external use, i.e. 9003 must be exposed to the public network for client SDKs to connect.
connectManager:
  wsPort: 9002
  proxyPort: 9003

# IM server-side API gateway listening port
apiGateway:
  httpPort: 8082

# IM admin console listening port
adminGateway:
  httpPort: 8090

5. Service Startup and Verification

• Start

In the deployment directory, imserver can be run directly.

• Port description

Port	Protocol	Description
9003	websocket	IM long-connection address, used by client SDKs to establish long connections. In a cluster deployment, you can use a load balancer to forward and expose the load balancer's IP/domain.
8082	http	IM server API address, used by business servers to call. Cluster deployment also requires a load balancer.
8090	http	IM admin console address. Cluster deployment requires a load balancer.

• Demo verification

After deployment, you can download the official JuggleIM demo, switch the server address to this private deployment, and experience it directly.

6. Choosing a Message Storage Engine

JuggleIM's message data supports three storage engines (MySQL / MongoDB / HBase). The following table briefly introduces the business volumes each can handle (for reference only).

Storage Engine	Use Case
MySQL	Daily messages under 1 billion; DAU under 30,000
MongoDB	Daily messages under 10 billion; DAU under 500,000
HBase	Daily messages over 10 billion; DAU over 500,000

---