🛠 Open Source Instant Messaging (IM) Project OpenIM Source Code Deployment Guide
Published: 2024-01-10 07:32:23


Deploying OpenIM involves multiple components and supports various methods, including source code, Docker, and Kubernetes. This requires ensuring compatibility between different deployment methods while effectively managing differences between versions. Indeed, these are complex issues involving in-depth technical details and precise system configurations. Our goal is to simplify the deployment process while maintaining the system's flexibility and stability to suit different users' needs. Currently, version 3.5 has simplified the deployment process, and this version will be maintained for a long time. We welcome everyone to use it.

## 1. Environment and Component Requirements

### 🌐 Environmental Requirements

| Note     | Detailed Description |
| -------- | -------------------- |
| OS       | Linux system         |
| Hardware | At least 4GB of RAM  |
| 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. Deploying OpenIM Server (IM)

### 2.1 📡 Setting OPENIM_IP

```bash
# If the server has an external IP
export OPENIM_IP="external IP"
# If only providing internal network services
export OPENIM_IP="internal IP"
```

### 2.2 🏗️ Deploying Components (mongodb/redis/zookeeper/kafka/MinIO, etc.)

```bash
git clone https://github.com/OpenIMSDK/open-im-server && cd open-im-server 
# It's recommended to switch to release-v3.5 or later release branches 
make init && docker compose up -d
```

### 2.3 🛠️ Compilation

```bash
make build
```

### 2.4 🚀 Starting/Stopping/Checking

```bash
# Start
make start
# Stop
make stop
# Check
make check
```

## 3. Deploying App Server (Chat)

### 3.1 🏗️ Deploying Components (mysql)

```bash
# Go back to the previous directory
cd ..
# Clone the repository, recommended to switch to release-v1.5 or later release branches
git clone https://github.com/OpenIMSDK/chat chat && cd chat
# Deploy mysql
docker run -d --name mysql2 -p 13306:3306 -p 33306:33060 -v "$(pwd)/components/mysql/data:/var/lib/mysql" -v "/etc/localtime:/etc/localtime" -e MYSQL_ROOT_PASSWORD="openIM123" --restart always mysql:5.7
```

### 3.2 🛠️ Compilation

```bash
make init
make build
```

### 3.3 🚀 Starting/Stopping/Checking

```bash
# Start
make start
# Stop
make stop
# Check
make check
```

## 4. Quick Validation

### 📡 Open Ports

#### IM Ports

| TCP Port  | Description                                                  | Action     |
| --------- | ------------------------------------------------------------ | ---------- |
| TCP:10001 | ws protocol, messaging port, for client SDK                  | Allow port |
| TCP:10002 | API port, like user, friend, group, message interfaces       | Allow port |
| TCP:10005 | Required when choosing MinIO storage (OpenIM defaults to MinIO storage) | Allow port |

#### Chat Ports

| TCP Port  | Description                                                | Action     |
| --------- | ---------------------------------------------------------- | ---------- |
| TCP:10008 | Business system, like registration, login, etc.            | Allow port |
| TCP:10009 | Management backend, like statistics, account banning, etc. | Allow port |

#### PC Web and Management Backend Frontend Resource Ports

| TCP Port  | Description                           | Action     |
| --------- | ------------------------------------- | ---------- |
| TCP:11001 | PC Web frontend resources             | Allow port |
| TCP:11002 | Management backend frontend resources | Allow port |

#### Grafana Port

| TCP Port  | Description  | Action     |
| --------- | ------------ | ---------- |
| TCP:13000 | Grafana port | Allow port |

---

## Verification

### PC Web Verification

**Note**: Enter `http://ip:11001` in your browser to access the PC Web. This IP should be the server's `OPENIM_IP` to ensure browser accessibility. For first-time use, please register using your mobile phone number, with the default verification code being `666666`.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7wt5wk7gfmshkq46a1bs.png)




*Image: PC Web Interface Example*

### App Verification

Scan the following QR code or click [here](https://www.pgyer.com/OpenIM-Flutter) to download.

![Download App](https://www.pgyer.com/app/qrcode/OpenIM-Flutter)
*Image: App Download QR Code*

**Note**: Double-click on OpenIM and change the IP to the server's `OPENIM_IP` then restart the App. Please ensure related ports are open, and restart the App after making changes. For first-time use, please register first through your mobile phone number, with the default verification code being `666666`.

![Server Address Modification - Step 1]


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8wj9i880f5srloperhi2.jpg)
*Image: Server Address Modification - Step 1*

![Server Address Modification - Step 2]

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vbll34kfee0jfr2p5kom.jpg)
*Image: Server Address Modification - Step 2*

## 5. Modifying Configuration Items

### 5.1 🛠️ Modifying Shared Configuration Items

| Configuration Item        | Files to be Modified                                         | Action                           |
| ------------------------- | ------------------------------------------------------------ | -------------------------------- |
| mongo/kafka/minio related | .env, openim-server/config/config.yaml                       | Restart components and IM        |
| redis/zookeeper related   | .env, openim-server/config/config.yaml, chat/config/config.yaml | Restart components, IM, and Chat |
| SECRET                    | openim-server/config/config.yaml, chat/config/config.yaml    | Restart IM and Chat              |

### 5.2 🔄 Modifying Special Configuration Items

Special configuration items: API_OPENIM_PORT/MINIO_PORT/OPENIM_IP/GRAFANA_PORT

1. Modify the special configuration items in the `.env` file
2. Modify the configuration in **`openim-server/config/config.yaml`** according to the rules
3. Modify the configuration in **`chat/config/config.yaml`** according to the rules
4. Restart IM and Chat

### 5.3 🛠️ Modifying Other Configuration Items

For other configuration items in **`.env`**, **`chat/config/config.yaml`**, and **`openim-server/config/config.yaml`**, you can modify these items directly in the respective files.

### 5.4 Modifying Ports

Note that for any modification of IM-related ports, it's necessary to synchronize the changes in **`open-im-server/scripts/install/environment.sh`**.

---

## 6. Frequently Asked Questions

### 6.1 📜 Viewing Logs

- Runtime logs: `logs/OpenIM.log.all.*`
- Startup logs: `_output/logs/openim_*.log`

### 6.2 🚀 Startup Order

The startup order is as follows:

1. Components IM depends on: mongo/redis/kafka/zookeeper/minio, etc.
2. **IM**
3. Components Chat depends on: mysql
4. **Chat**

### 6.3 🐳 Docker Version

- The new version of Docker has integrated docker-compose.
- Older versions of Docker might not support the gateway feature. It's recommended to upgrade to a newer version, such as `23.0.1`.

## 7. About OpenIM

Thanks to widespread developer support, OpenIM maintains a leading position in the open-source instant messaging (IM) field, with the number of stars on Github exceeding 12,000. In the current context of increasing attention to data and privacy security, the demand for IM private deployment is growing, which aligns with the rapid development trend of China's software industry. Especially in government and enterprise sectors, with the rapid development of information technology and the widespread application of innovative

 industries, the demand for IM solutions has surged. Further, the continuous expansion of the collaborative office software market has made "secure and controllable" a key attribute.

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iqgwc107hd1899cz6p4b.jpg)