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

```jsx

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

```

## 2.2 Set OPENIM_IP

```jsx

# 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

```jsx

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](https://www.pgyer.com/OpenIM-Flutter) 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`**:

```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