OpenIM Open Source Instant Messaging Project Docker Compose Deployment Guide

The deployment of OpenIM involves multiple components and supports various methods including source code, Docker, and Kubernetes. This requires ensuring compatibility between different deployment methods and effectively managing differences between versions. This is undoubtedly a complex task involving technical depth and precise system configuration. We are committed to simplifying the deployment process while ensuring the system’s flexibility and stability, to meet the needs of various users. Currently, in version 3.5, we have simplified the deployment process and will provide long-term maintenance for this version, looking forward to your user experience.

1. Environment and Component Requirements

🌐 Environmental Requirements

| Note | Detailed Explanation |

| ------------------ | ----------------------------- |

| Operating System | Linux system |

| Hardware Resources | At least 4GB available memory |

| Golang | v1.19 or higher |

| Docker | v24.0.5 or higher |

| Git | v2.17.1 or higher |

Storage Component Requirements

| Storage Component | Recommended Version |

| ----------------- | ------------------- |

| MongoDB | v6.0.2 or higher |

| Redis | v7.0.0 or higher |

| Zookeeper | v3.8 |

| Kafka | v3.5.1 |

| MySQL | v5.7 or higher |

| MinIO | Latest version |

2. Docker Deployment

2.1 Clone Repository and Initialize

git clone https://github.com/openimsdk/openim-docker openim-docker && cd openim-docker && make init

2.2 Set OPENIM_IP

# If the server has an external IP

export OPENIM_IP="external IP"

# If only providing internal network services

export OPENIM_IP="internal IP"

2.3 Start Services and View Logs

docker compose up -d

docker ps

docker compose logs -f openim-chat

docker compose logs -f openim-server

3. Quick Verification

Open Ports

IM Ports

| TCP Port | Description | Action |

| --------- | ------------------------------------------------------------ | --------- |

| TCP:10001 | ws protocol, message port, for client SDK | Open Port |

| TCP:10002 | api port, such as user, friend, group, message, etc. | Open Port |

| TCP:10005 | Needed when choosing MinIO storage (OpenIM defaults to MinIO storage) | Open Port |

Chat Ports

| TCP Port | Description | Action |

| --------- | ----------------------------------------------------- | --------- |

| TCP:10008 | Business system, such as registration, login, etc. | Open Port |

| TCP:10009 | Management backend, such as statistics, banning, etc. | Open Port |

PC Web and Management Backend Frontend Resource Ports

| TCP Port | Description | Action |

| --------- | ------------------------------------- | --------- |

| TCP:11001 | PC Web frontend resources | Open Port |

| TCP:11002 | Management backend frontend resources | Open Port |

Grafana Port

| TCP Port | Description | Action |

| --------- | ------------ | --------- |

| TCP:13000 | grafana port | Open Port |

4. Verification

PC Web Verification

Note: Enter http://ip:11001 in the browser to access PC Web. This IP should be the server’s OPENIM_IP, ensuring browser access. Please register via mobile phone for first-time use, the default verification code is 666666.

Image: PC Web Interface Example

App Verification

Scan the QR code below or click here to download.

Image: App Download QR Code

Note: Double-click on OpenIM and modify the IP to the server’s OPENIM_IP, then restart the App. Please ensure relevant ports are open and restart the App after modification. Register via mobile phone for first-time use, the default verification code is 666666.

Image: Server Address Modification - Step 1

Image: Server Address Modification - Step 2

5. About Configuration Item Modifications

This project has complex configuration items, mainly because some configurations involve .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml files. The explanation for modifying configuration items is divided into two parts: modifications for shared configuration items and other configuration items.

5.1 Shared Configuration Items

Shared configuration items in .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml:

1. Ports and passwords for mysql/mongo/redis/kafka/zookeeper/minio;

2. SECRET;

3. API_OPENIM_PORT;

4. OPENIM_IP;

5. MINIO_PORT;

6. GRAFANA_PORT.

5.2 Modification Methods

For the shared configuration items in 5.1, choose one of the following two methods.

Method One: Regenerate All Configurations

If a comprehensive update is needed, follow these steps:

1. Delete existing configuration files: Remove openim-server/config/config.yaml and openim-chat/config/config.yaml files.

2. Modify .env file: Update related configuration items in the .env file.

3. Regenerate configurations and restart services: Execute docker compose down ; docker compose up -d. This will regenerate configuration files based on the new settings in the .env file and restart the services.

Method Two: Modify Multiple Configuration Files Separately

For partial updates, follow these steps:

1. Modify .env file: Update related configuration items in the .env file.

2. Manually update configuration files: According to the modifications in the .env file, update the corresponding configuration items in the openim-server/config/config.yaml and openim-chat/config/config.yaml files.

3. Additional handling for special variables: If OPENIM_IP, API_OPENIM_PORT, MINIO_PORT, GRAFANA_PORT are modified, update the following configuration items in the openim-server/config/config.yaml:

object:

apiURL: "http://$OPENIM_IP:$API_OPENIM_PORT"

minio:

endpoint: "http://$DOCKER_BRIDGE_GATEWAY:$MINIO_PORT"

signEndpoint: "http://$OPENIM_IP:$MINIO_PORT"

grafanaUrl: http://$OPENIM_IP:$GRAFANA_PORT

4. Restart services: Execute docker compose down ; docker compose up -d to apply changes and restart services.

5.3 Modifying Other Configuration Items

For non-shared variables in .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml, modify these configuration items directly in the respective files. Execute docker compose down ; docker compose up -d to apply changes and restart services.

6. Frequently Asked Questions 🧐

1. About Docker Version 🐋

Newer versions of Docker have integrated docker-compose. Older versions of Docker may not support the gateway feature. We recommend upgrading to a newer version, such as 23.0.1.

7. About OpenIM

Thanks to extensive developer support, OpenIM maintains a leading position in the open-source instant messaging (IM) field, with its GitHub stars surpassing 12,000. In the current context of increasing emphasis on data and privacy security, there is growing demand for IM private deployment, aligning with the rapid development trend of China’s software industry. Especially in government and enterprise sectors, with the rapid development of information technology and widespread application of innovative industries, the demand for IM solutions has surged. Furthermore, the continuous expansion of the collaborative office software market has made “security and controllability” a key attribute.

Repository address: https://github.com/openimsdk