msb-public
/
Open-IM-Server
mirror of https://github.com/OpenIMSDK/Open-IM-Server
2
0
Code Issues Projects Releases Wiki Activity

docs: add openim docs (#1165)

Browse Source 
Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com>
pull/1155/head
Xinwei Xiong 1 year ago committed by GitHub
parent c5f6514f98
commit b72b72f74f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 433 additions and 133 deletions
Show Stats Download Patch File Download Diff File

550
docs/contrib/environment.md
Unescape View File

@ -1,212 +1,504 @@
# OpenIM enviroment
## How to change the configuration
**Modify the configuration files:**
Three ways to modify the configuration:
#### **1. Recommended using environment variables:**
<!-- vscode-markdown-toc -->
* 1. [OpenIM Deployment Guide](#OpenIMDeploymentGuide)
* 1.1. [Deployment Strategies](#DeploymentStrategies)
* 1.2. [Source Code Deployment](#SourceCodeDeployment)
* 1.3. [Docker Compose Deployment](#DockerComposeDeployment)
* 1.4. [Environment Variable Configuration](#EnvironmentVariableConfiguration)
* 1.4.1. [[1. Recommended using environment variables:](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#1-recommended-using-environment-variables)](#1.Recommendedusingenvironmentvariables:https:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.md1-recommended-using-environment-variables)
* 1.4.2. [[Additional Configuration](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#additional-configuration)](#AdditionalConfigurationhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdadditional-configuration)
* 1.4.3. [[Security Considerations](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#security-considerations)](#SecurityConsiderationshttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdsecurity-considerations)
* 1.4.4. [[Data Management](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#data-management)](#DataManagementhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mddata-management)
* 1.4.5. [[Monitoring and Logging](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#monitoring-and-logging)](#MonitoringandLogginghttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdmonitoring-and-logging)
* 1.4.6. [[Troubleshooting](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#troubleshooting)](#Troubleshootinghttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdtroubleshooting)
* 1.4.7. [[Conclusion](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#conclusion)](#Conclusionhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdconclusion)
* 1.4.8. [[Additional Resources](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#additional-resources)](#AdditionalResourceshttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdadditional-resources)
* 2. [Further Configuration](#FurtherConfiguration)
* 2.1. [Image Registry Configuration](#ImageRegistryConfiguration)
* 2.2. [OpenIM Docker Network Configuration](#OpenIMDockerNetworkConfiguration)
* 2.3. [OpenIM Configuration](#OpenIMConfiguration)
* 2.4. [OpenIM Chat Configuration](#OpenIMChatConfiguration)
* 2.5. [Zookeeper Configuration](#ZookeeperConfiguration)
* 2.6. [MySQL Configuration](#MySQLConfiguration)
* 2.7. [MongoDB Configuration](#MongoDBConfiguration)
* 2.8. [Tencent Cloud COS Configuration](#TencentCloudCOSConfiguration)
* 2.9. [Alibaba Cloud OSS Configuration](#AlibabaCloudOSSConfiguration)
* 2.10. [Redis Configuration](#RedisConfiguration)
* 2.11. [Kafka Configuration](#KafkaConfiguration)
* 2.12. [OpenIM Web Configuration](#OpenIMWebConfiguration)
* 2.13. [RPC Configuration](#RPCConfiguration)
* 2.14. [Prometheus Configuration](#PrometheusConfiguration)
* 2.15. [Grafana Configuration](#GrafanaConfiguration)
* 2.16. [RPC Port Configuration Variables](#RPCPortConfigurationVariables)
* 2.17. [RPC Register Name Configuration](#RPCRegisterNameConfiguration)
* 2.18. [Log Configuration](#LogConfiguration)
* 2.19. [Additional Configuration Variables](#AdditionalConfigurationVariables)
* 2.20. [Prometheus Configuration](#PrometheusConfiguration-1)
* 2.20.1. [General Configuration](#GeneralConfiguration)
* 2.20.2. [Service-Specific Prometheus Ports](#Service-SpecificPrometheusPorts)
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->
## 1. <a name='OpenIMDeploymentGuide'></a>OpenIM Deployment Guide
Welcome to the OpenIM Deployment Guide! OpenIM offers a versatile and robust instant messaging server, and deploying it can be achieved through various methods. This guide will walk you through the primary deployment strategies, ensuring you can set up OpenIM in a way that best suits your needs.
### 1.1. <a name='DeploymentStrategies'></a>Deployment Strategies
OpenIM provides multiple deployment methods, each tailored to different use cases and technical preferences:
1. **[Source Code Deployment Guide](https://doc.rentsoft.cn/guides/gettingStarted/imSourceCodeDeployment)**
2. **[Docker Deployment Guide](https://doc.rentsoft.cn/guides/gettingStarted/dockerCompose)**
3. **[Kubernetes Deployment Guide](https://github.com/openimsdk/open-im-server/tree/main/deployments)**
While the first two methods will be our main focus, it's worth noting that the third method, Kubernetes deployment, is also viable and can be rendered via the `environment.sh` script variables.
### 1.2. <a name='SourceCodeDeployment'></a>Source Code Deployment
In the source code deployment method, the configuration generation process involves executing `make init`, which fundamentally runs the script `./scripts/init-config.sh`. This script utilizes variables defined in the [`environment.sh`](https://github.com/openimsdk/open-im-server/blob/main/scripts/install/environment.sh) script to render the [`openim.yaml`](https://github.com/openimsdk/open-im-server/blob/main/deployments/templates/openim.yaml) template file, subsequently generating the [`config.yaml`](https://github.com/openimsdk/open-im-server/blob/main/config/config.yaml) configuration file.
### 1.3. <a name='DockerComposeDeployment'></a>Docker Compose Deployment
Docker deployment offers a slightly more intricate template. Within the [openim-server](https://github.com/openimsdk/openim-docker/tree/main/openim-server) directory, multiple subdirectories correspond to various versions, each aligning with `openim-chat` as illustrated below:
| openim-server | openim-chat |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [main](https://github.com/openimsdk/openim-docker/tree/main/openim-server/main) | [main](https://github.com/openimsdk/openim-docker/tree/main/openim-chat/main) |
| [release-v3.2](https://github.com/openimsdk/openim-docker/tree/main/openim-server/release-v3.3) | [release-v3.2](https://github.com/openimsdk/openim-docker/tree/main/openim-chat/release-v1.3) |
| [release-v3.2](https://github.com/openimsdk/openim-docker/tree/main/openim-server/release-v3.2) | [release-v3.2](https://github.com/openimsdk/openim-docker/tree/main/openim-chat/release-v1.2) |
Configuration file modifications can be made by specifying corresponding environment variables, for instance:
```bash
export PASSWORD="openIM123" # Set password
export USER="root" # Set username
# Choose chat version and server version https://github.com/openimsdk/open-im-server/blob/main/docs/conversions/images.md, eg: main, release-v*.*
export CHAT_BRANCH="main"
export SERVER_BRANCH="main"
#... Other environment variables
# MONGO_USERNAME: This sets the MongoDB username
# MONGO_PASSWORD: Set the MongoDB password
# MONGO_DATABASE: Sets the MongoDB database name
# MINIO_ENDPOINT: set the MinIO service address
# API_URL: under network environment, set OpenIM Server API address
export API_URL="http://127.0.0.1:10002"
```
Next, update the configuration using `make init`:
These variables are stored within the [`environment.sh`](https://github.com/OpenIMSDK/openim-docker/blob/main/scripts/install/environment.sh) configuration:
```bash
make init
readonly CHAT_BRANCH=${CHAT_BRANCH:-'main'}
readonly SERVER_BRANCH=${SERVER_BRANCH:-'main'}
```
#### **2. Modify the automation script:**
Setting a variable, e.g., `export CHAT_BRANCH="release-v1.3"`, will prioritize `CHAT_BRANCH="release-v1.3"` as the variable value. Ultimately, the chosen image version is determined, and rendering is achieved through `make init` (or `./scripts/init-config.sh`).
> Note: Direct modifications to the `config.yaml` file are also permissible without utilizing `make init`.
### 1.4. <a name='EnvironmentVariableConfiguration'></a>Environment Variable Configuration
For convenience, configuration through modifying environment variables is recommended:
#### 1.4.1. <a name='1.Recommendedusingenvironmentvariables:https:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.md1-recommended-using-environment-variables'></a>[1. Recommended using environment variables:](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#1-recommended-using-environment-variables)
+ PASSWORD
+ **Description**: Password for mysql, mongodb, redis, and minio.
+ **Default**: `openIM123`
+ Notes:
+ Minimum password length: 8 characters.
+ Special characters are not allowed.
```bash
scripts/install/environment.sh
export PASSWORD="openIM123"
```
Next, update the configuration using `make init`:
+ USER
+ **Description**: Username for mysql, mongodb, redis, and minio.
+ **Default**: `root`
```bash
make init
export USER="root"
```
#### 3. Modify `config.yaml` and `.env` files (but will be overwritten when using `make init` again).
The `config/config.yaml` file has detailed configuration instructions for the storage components.
+ API_URL
+ **Description**: API address.
+ **Note**: If the server has an external IP, it will be automatically obtained. For internal networks, set this variable to the IP serving internally.
The config file is available via [environment.sh](https://github.com/openimsdk/open-im-server/blob/main/scripts/install/environment.sh) configuration [openim.yaml](https://github.com/openimsdk/open-im-server/blob/main/deployments/templates/openim.yaml) template, and then through the `make init` to automatically generate a new configuration.
```
export API_URL="http://ip:10002"
```
+ DATA_DIR
## Environment variable
+ **Description**: Data mount directory for components.
+ **Default**: `/data/openim`
By setting the environment variable below, You can then refresh the configuration using `make init` or `./scripts/init-config.sh`
```bash
export DATA_DIR="/data/openim"
```
##### MINIO
#### 1.4.2. <a name='AdditionalConfigurationhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdadditional-configuration'></a>[Additional Configuration](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#additional-configuration)
+ [MINIO DOCS](https://min.io/docs/minio/kubernetes/upstream/index.html)
##### [MinIO Access and Secret Key](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#minio-access-and-secret-key)
apiURL is the address of the api, the access address of the app, use s3 must be configured
To secure your MinIO server, you should set up an access key and secret key. These credentials are used to authenticate requests to your MinIO server.
#### Overview
```bash
export MINIO_ACCESS_KEY="YourAccessKey"
export MINIO_SECRET_KEY="YourSecretKey"
```
MinIO is an object storage server that is API compatible with Amazon S3. It's best suited for storing unstructured data such as photos, videos, log files, backups, and container/VM images. In this guide, we'll walk through the process of configuring MinIO with custom settings.
##### [MinIO Browser](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#minio-browser)
#### Default Configuration
MinIO comes with an embedded web-based object browser. You can control the availability of the MinIO browser by setting the `MINIO_BROWSER` environment variable.
Configuration can be achieved by modifying the default variables in the `./scripts/install/environment.sh` file. However, for more flexibility and dynamic adjustments, setting environment variables is recommended.
```bash
export MINIO_BROWSER="on"
```
#### Setting Up the Environment Variables
#### 1.4.3. <a name='SecurityConsiderationshttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdsecurity-considerations'></a>[Security Considerations](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#security-considerations)
##### IP Configuration
##### [TLS/SSL Configuration](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#tls-ssl-configuration)
By default, the system generates the public IP of the machine. To manually set a public or local IP address, use:
For secure communication, it's recommended to enable TLS/SSL for your MinIO server. You can do this by providing the path to the SSL certificate and key files.
```bash
export IP=127.0.0.1
export MINIO_CERTS_DIR="/path/to/certs/directory"
```
##### API URL
#### 1.4.4. <a name='DataManagementhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mddata-management'></a>[Data Management](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#data-management)
##### [Data Retention Policy](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#data-retention-policy)
This is the address your application uses to communicate with MinIO. By default, it uses the public IP. However, you can adjust it to a public domain or another IP.
You may want to set up a data retention policy to automatically delete objects after a specified period.
```bash
export API_URL=127.0.0.1:10002
export MINIO_RETENTION_DAYS="30"
```
##### MinIO Endpoint Configuration
#### 1.4.5. <a name='MonitoringandLogginghttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdmonitoring-and-logging'></a>[Monitoring and Logging](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#monitoring-and-logging)
##### [Audit Logging](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#audit-logging)
This is the primary address MinIO uses for communications:
Enable audit logging to keep track of access and changes to your data.
```bash
export MINIO_ENDPOINT="127.0.0.1"
export MINIO_AUDIT="on"
```
##### MinIO Sign Endpoint
#### 1.4.6. <a name='Troubleshootinghttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdtroubleshooting'></a>[Troubleshooting](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#troubleshooting)
For direct external access to stored content:
##### [Debug Mode](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#debug-mode)
In case of issues, you may enable debug mode to get more detailed logs to assist in troubleshooting.
```bash
export MINIO_SIGN_ENDPOINT=127.0.0.1:10005
export MINIO_DEBUG="on"
```
##### Modifying MinIO's Port
#### 1.4.7. <a name='Conclusionhttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdconclusion'></a>[Conclusion](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#conclusion)
If you need to adjust MinIO's port from the default:
With the environment variables configured as per your requirements, your MinIO server should be ready to securely store and manage your object data. Ensure to verify the setup and monitor the logs for any unusual activities or errors. Regularly update the MinIO server and review your configuration to adapt to any changes or improvements in the MinIO system.
```bash
export MINIO_PORT="10005"
```
#### 1.4.8. <a name='AdditionalResourceshttps:github.comopenimsdkopen-im-serverblobmaindocscontribenvironment.mdadditional-resources'></a>[Additional Resources](https://github.com/openimsdk/open-im-server/blob/main/docs/contrib/environment.md#additional-resources)
#### Applying the Configuration
+ [MinIO Client Quickstart Guide](https://docs.min.io/docs/minio-client-quickstart-guide)
+ [MinIO Admin Complete Guide](https://docs.min.io/docs/minio-admin-complete-guide)
+ [MinIO Docker Quickstart Guide](https://docs.min.io/docs/minio-docker-quickstart-guide)
After setting your desired environment variables, restart the MinIO server to apply the changes.
Feel free to explore the MinIO documentation for more advanced configurations and usage scenarios.
#### Verification
It's crucial to verify the configurations by checking the connectivity between your application and MinIO using the set API URL and ensuring that the data can be directly accessed using the `signEndpoint`.
## 2. <a name='FurtherConfiguration'></a>Further Configuration
## Configuration Details
### 2.1. <a name='ImageRegistryConfiguration'></a>Image Registry Configuration
###### Zookeeper
**Description**: The image registry configuration allows users to select an image address for use. The default is set to use GITHUB images, but users can opt for Docker Hub or Ali Cloud, especially beneficial for Chinese users due to its local proximity.
- **Purpose**: Used for RPC service discovery and registration, cluster support.
| Parameter | Default Value | Description |
| ---------------- | --------------------- | ------------------------------------------------------------ |
| `IMAGE_REGISTRY` | `"ghcr.io/openimsdk"` | The registry from which Docker images will be pulled. Other options include `"openim"` and `"registry.cn-hangzhou.aliyuncs.com/openimsdk"`. |
```bash
zookeeper:
schema: openim # Not recommended to modify
address: [ 127.0.0.1:2181 ] # Address
username: # Username
password: # Password
```
### 2.2. <a name='OpenIMDockerNetworkConfiguration'></a>OpenIM Docker Network Configuration
###### MySQL
**Description**: This section configures the Docker network subnet and generates IP addresses for various services within the defined subnet.
- **Purpose**: Used for storing users, relationships, and groups. Supports master-slave database.
| Parameter | Example Value | Description |
| --------------------------- | ----------------- | ------------------------------------------------------------ |
| `DOCKER_BRIDGE_SUBNET` | `'172.28.0.0/16'` | The subnet for the Docker network. |
| `DOCKER_BRIDGE_GATEWAY` | Generated IP | The gateway IP address within the Docker subnet. |
| `[SERVICE]_NETWORK_ADDRESS` | Generated IP | The network IP address for a specific service (e.g., MYSQL, MONGO, REDIS, etc.) within the Docker subnet. |
```bash
mysql:
address: [ 127.0.0.1:13306 ] # Address
username: root # Username
password: openIM123 # Password
database: openIM_v2 # Not recommended to modify
maxOpenConn: 1000 # Maximum connection
maxIdleConn: 100 # Maximum idle connection
maxLifeTime: 60 # Max time a connection can be reused (seconds)
logLevel: 4 # Log level (1=silent, 2=error, 3=warn, 4=info)
slowThreshold: 500 # Slow statement threshold (milliseconds)
```
### 2.3. <a name='OpenIMConfiguration'></a>OpenIM Configuration
###### Mongo
**Description**: OpenIM configuration involves setting up directories for data, installation, configuration, and logs. It also involves configuring the OpenIM server address and ports for WebSocket and API.
- **Purpose**: Used for storing offline messages. Supports mongo sharded clusters.
| Parameter | Default Value | Description |
| ----------------------- | ------------------------ | ----------------------------------------- |
| `OPENIM_DATA_DIR` | `"/data/openim"` | Directory for OpenIM data. |
| `OPENIM_INSTALL_DIR` | `"/opt/openim"` | Directory where OpenIM is installed. |
| `OPENIM_CONFIG_DIR` | `"/etc/openim"` | Directory for OpenIM configuration files. |
| `OPENIM_LOG_DIR` | `"/var/log/openim"` | Directory for OpenIM logs. |
| `OPENIM_SERVER_ADDRESS` | Docker Bridge Gateway IP | OpenIM server address. |
| `OPENIM_WS_PORT` | `'10001'` | Port for OpenIM WebSocket. |
| `API_OPENIM_PORT` | `'10002'` | Port for OpenIM API. |
```bash
mongo:
uri: # Use this value directly if not empty
address: [ 127.0.0.1:37017 ] # Address
database: openIM # Default mongo db
username: root # Username
password: openIM123 # Password
maxPoolSize: 100 # Maximum connections
```
### 2.4. <a name='OpenIMChatConfiguration'></a>OpenIM Chat Configuration
###### Redis
**Description**: Configuration for OpenIM chat, including data directory, server address, and ports for API and chat functionalities.
- **Purpose**: Used for storing message sequence numbers, latest messages, user tokens, and MySQL cache. Supports cluster deployment.
| Parameter | Example Value | Description |
| ----------------------- | -------------------------- | ------------------------------- |
| `OPENIM_CHAT_DATA_DIR` | `"./openim-chat/[BRANCH]"` | Directory for OpenIM chat data. |
| `OPENIM_CHAT_ADDRESS` | Docker Bridge Gateway IP | OpenIM chat service address. |
| `OPENIM_CHAT_API_PORT` | `"10008"` | Port for OpenIM chat API. |
| `OPENIM_ADMIN_API_PORT` | `"10009"` | Port for OpenIM Admin API. |
| `OPENIM_ADMIN_PORT` | `"30200"` | Port for OpenIM chat Admin. |
| `OPENIM_CHAT_PORT` | `"30300"` | Port for OpenIM chat. |
```bash
redis:
address: [ 127.0.0.1:16379 ] # Address
username: # Username
password: openIM123 # Password
```
### 2.5. <a name='ZookeeperConfiguration'></a>Zookeeper Configuration
###### Kafka
**Description**: Configuration for Zookeeper, including schema, port, address, and credentials.
- **Purpose**: Used for message queues for decoupling. Supports cluster deployment.
| Parameter | Example Value | Description |
| -------------------- | ------------------------ | ----------------------- |
| `ZOOKEEPER_SCHEMA` | `"openim"` | Schema for Zookeeper. |
| `ZOOKEEPER_PORT` | `"12181"` | Port for Zookeeper. |
| `ZOOKEEPER_ADDRESS` | Docker Bridge Gateway IP | Address for Zookeeper. |
| `ZOOKEEPER_USERNAME` | `""` | Username for Zookeeper. |
| `ZOOKEEPER_PASSWORD` | `""` | Password for Zookeeper. |
```bash
kafka:
username: # Username
password: # Password
addr: [ 127.0.0.1:9092 ] # Address
topics:
latestMsgToRedis: "latestMsgToRedis"
offlineMsgToMongo: "offlineMsgToMongoMysql"
msgToPush: "msgToPush"
msgToModify: "msgToModify"
consumerGroupID:
msgToRedis: redis
msgToMongo: mongo
msgToMySql: mysql
msgToPush: push
msgToModify: modify
```
### 2.6. <a name='MySQLConfiguration'></a>MySQL Configuration
**Description**: Configuration for MySQL, including port, address, and credentials.
## Config options
| Parameter | Example Value | Description |
| ---------------- | ------------------------ | ------------------- |
| `MYSQL_PORT` | `"13306"` | Port for MySQL. |
| `MYSQL_ADDRESS` | Docker Bridge Gateway IP | Address for MySQL. |
| `MYSQL_USERNAME` | User-defined | Username for MySQL. |
| `MYSQL_PASSWORD` | User-defined | Password for MySQL. |
...
Note: The configurations for other services (e.g., MONGO, REDIS, KAFKA, etc.) follow a similar pattern to MySQL and can be documented in a similar manner.
## Use the default values
### 2.7. <a name='MongoDBConfiguration'></a>MongoDB Configuration
A method to revert to the default value:
This section involves setting up MongoDB, including its port, address, and credentials.
```bash
export IP=127.0.0.1
```
| Parameter | Example Value | Description |
| -------------- | -------------- | ----------------------- |
| MONGO_PORT | "27017" | Port used by MongoDB. |
| MONGO_ADDRESS | [Generated IP] | IP address for MongoDB. |
| MONGO_USERNAME | [User Defined] | Username for MongoDB. |
| MONGO_PASSWORD | [User Defined] | Password for MongoDB. |
### 2.8. <a name='TencentCloudCOSConfiguration'></a>Tencent Cloud COS Configuration
This section involves setting up Tencent Cloud COS, including its bucket URL and credentials.
| Parameter | Example Value | Description |
| ----------------- | ------------------------------------------------------------ | ------------------------------------ |
| COS_BUCKET_URL | "[https://temp-1252357374.cos.ap-chengdu.myqcloud.com](https://temp-1252357374.cos.ap-chengdu.myqcloud.com/)" | Tencent Cloud COS bucket URL. |
| COS_SECRET_ID | [User Defined] | Secret ID for Tencent Cloud COS. |
| COS_SECRET_KEY | [User Defined] | Secret key for Tencent Cloud COS. |
| COS_SESSION_TOKEN | [User Defined] | Session token for Tencent Cloud COS. |
| COS_PUBLIC_READ | "false" | Public read access. |
### 2.9. <a name='AlibabaCloudOSSConfiguration'></a>Alibaba Cloud OSS Configuration
This section involves setting up Alibaba Cloud OSS, including its endpoint, bucket name, and credentials.
| Parameter | Example Value | Description |
| --------------------- | ------------------------------------------------------------ | ---------------------------------------- |
| OSS_ENDPOINT | "[https://oss-cn-chengdu.aliyuncs.com](https://oss-cn-chengdu.aliyuncs.com/)" | Endpoint URL for Alibaba Cloud OSS. |
| OSS_BUCKET | "demo-9999999" | Bucket name for Alibaba Cloud OSS. |
| OSS_BUCKET_URL | "[https://demo-9999999.oss-cn-chengdu.aliyuncs.com](https://demo-9999999.oss-cn-chengdu.aliyuncs.com/)" | Bucket URL for Alibaba Cloud OSS. |
| OSS_ACCESS_KEY_ID | [User Defined] | Access key ID for Alibaba Cloud OSS. |
| OSS_ACCESS_KEY_SECRET | [User Defined] | Access key secret for Alibaba Cloud OSS. |
| OSS_SESSION_TOKEN | [User Defined] | Session token for Alibaba Cloud OSS. |
| OSS_PUBLIC_READ | "false" | Public read access. |
### 2.10. <a name='RedisConfiguration'></a>Redis Configuration
This section involves setting up Redis, including its port, address, and credentials.
| Parameter | Example Value | Description |
| -------------- | -------------------------- | --------------------- |
| REDIS_PORT | "16379" | Port used by Redis. |
| REDIS_ADDRESS | "${DOCKER_BRIDGE_GATEWAY}" | IP address for Redis. |
| REDIS_USERNAME | [User Defined] | Username for Redis. |
| REDIS_PASSWORD | "${PASSWORD}" | Password for Redis. |
### 2.11. <a name='KafkaConfiguration'></a>Kafka Configuration
This section involves setting up Kafka, including its port, address, credentials, and topics.
| Parameter | Example Value | Description |
| ---------------------------- | -------------------------- | ----------------------------------- |
| KAFKA_USERNAME | [User Defined] | Username for Kafka. |
| KAFKA_PASSWORD | [User Defined] | Password for Kafka. |
| KAFKA_PORT | "19094" | Port used by Kafka. |
| KAFKA_ADDRESS | "${DOCKER_BRIDGE_GATEWAY}" | IP address for Kafka. |
| KAFKA_LATESTMSG_REDIS_TOPIC | "latestMsgToRedis" | Topic for latest message to Redis. |
| KAFKA_OFFLINEMSG_MONGO_TOPIC | "offlineMsgToMongoMysql" | Topic for offline message to Mongo. |
| KAFKA_MSG_PUSH_TOPIC | "msgToPush" | Topic for message to push. |
| KAFKA_CONSUMERGROUPID_REDIS | "redis" | Consumer group ID to Redis. |
| KAFKA_CONSUMERGROUPID_MONGO | "mongo" | Consumer group ID to Mongo. |
| KAFKA_CONSUMERGROUPID_MYSQL | "mysql" | Consumer group ID to MySQL. |
| KAFKA_CONSUMERGROUPID_PUSH | "push" | Consumer group ID to push. |
Note: Ensure to replace placeholder values (like [User Defined], `${DOCKER_BRIDGE_GATEWAY}`, and `${PASSWORD}`) with actual values before deploying the configuration.
### 2.12. <a name='OpenIMWebConfiguration'></a>OpenIM Web Configuration
This section involves setting up OpenIM Web, including its port, address, and dist path.
| Parameter | Example Value | Description |
| -------------------- | -------------------------- | ------------------------- |
| OPENIM_WEB_PORT | "11001" | Port used by OpenIM Web. |
| OPENIM_WEB_ADDRESS | "${DOCKER_BRIDGE_GATEWAY}" | Address for OpenIM Web. |
| OPENIM_WEB_DIST_PATH | "/app/dist" | Dist path for OpenIM Web. |
### 2.13. <a name='RPCConfiguration'></a>RPC Configuration
Configuration for RPC, including the register and listen IP.
| Parameter | Example Value | Description |
| --------------- | -------------- | -------------------- |
| RPC_REGISTER_IP | [User Defined] | Register IP for RPC. |
| RPC_LISTEN_IP | "0.0.0.0" | Listen IP for RPC. |
### 2.14. <a name='PrometheusConfiguration'></a>Prometheus Configuration
Setting up Prometheus, including its port and address.
| Parameter | Example Value | Description |
| ------------------ | -------------------------- | ------------------------ |
| PROMETHEUS_PORT | "19090" | Port used by Prometheus. |
| PROMETHEUS_ADDRESS | "${DOCKER_BRIDGE_GATEWAY}" | Address for Prometheus. |
### 2.15. <a name='GrafanaConfiguration'></a>Grafana Configuration
Configuration for Grafana, including its port and address.
| Parameter | Example Value | Description |
| --------------- | -------------------------- | --------------------- |
| GRAFANA_PORT | "3000" | Port used by Grafana. |
| GRAFANA_ADDRESS | "${DOCKER_BRIDGE_GATEWAY}" | Address for Grafana. |
### 2.16. <a name='RPCPortConfigurationVariables'></a>RPC Port Configuration Variables
Configuration for various RPC ports. Note: For launching multiple programs, just fill in multiple ports separated by commas. Try not to have spaces.
| Parameter | Example Value | Description |
| --------------------------- | ------------- | ----------------------------------- |
| OPENIM_USER_PORT | '10110' | OpenIM User Service Port. |
| OPENIM_FRIEND_PORT | '10120' | OpenIM Friend Service Port. |
| OPENIM_MESSAGE_PORT | '10130' | OpenIM Message Service Port. |
| OPENIM_MESSAGE_GATEWAY_PORT | '10140' | OpenIM Message Gateway Service Port |
| OPENIM_GROUP_PORT | '10150' | OpenIM Group Service Port. |
| OPENIM_AUTH_PORT | '10160' | OpenIM Authorization Service Port. |
| OPENIM_PUSH_PORT | '10170' | OpenIM Push Service Port. |
| OPENIM_CONVERSATION_PORT | '10180' | OpenIM Conversation Service Port. |
| OPENIM_THIRD_PORT | '10190' | OpenIM Third-Party Service Port. |
### 2.17. <a name='RPCRegisterNameConfiguration'></a>RPC Register Name Configuration
This section involves setting up the RPC Register Names for various OpenIM services.
| Parameter | Example Value | Description |
| --------------------------- | ---------------- | ----------------------------------- |
| OPENIM_USER_NAME | "User" | OpenIM User Service Name |
| OPENIM_FRIEND_NAME | "Friend" | OpenIM Friend Service Name |
| OPENIM_MSG_NAME | "Msg" | OpenIM Message Service Name |
| OPENIM_PUSH_NAME | "Push" | OpenIM Push Service Name |
| OPENIM_MESSAGE_GATEWAY_NAME | "MessageGateway" | OpenIM Message Gateway Service Name |
| OPENIM_GROUP_NAME | "Group" | OpenIM Group Service Name |
| OPENIM_AUTH_NAME | "Auth" | OpenIM Authorization Service Name |
| OPENIM_CONVERSATION_NAME | "Conversation" | OpenIM Conversation Service Name |
| OPENIM_THIRD_NAME | "Third" | OpenIM Third-Party Service Name |
### 2.18. <a name='LogConfiguration'></a>Log Configuration
This section involves configuring the log settings, including storage location, rotation time, and log level.
| Parameter | Example Value | Description |
| ------------------------- | ------------------------ | --------------------------------- |
| LOG_STORAGE_LOCATION | ""${OPENIM_ROOT}"/logs/" | Location for storing logs |
| LOG_ROTATION_TIME | "24" | Log rotation time (in hours) |
| LOG_REMAIN_ROTATION_COUNT | "2" | Number of log rotations to retain |
| LOG_REMAIN_LOG_LEVEL | "6" | Log level to retain |
| LOG_IS_STDOUT | "false" | Output log to standard output |
| LOG_IS_JSON | "false" | Log in JSON format |
| LOG_WITH_STACK | "false" | Include stack info in logs |
### 2.19. <a name='AdditionalConfigurationVariables'></a>Additional Configuration Variables
This section involves setting up additional configuration variables for Websocket, Push Notifications, and Chat.
| Parameter | Example Value | Description |
| ----------------------- | ----------------- | ---------------------------------- |
| WEBSOCKET_MAX_CONN_NUM | "100000" | Maximum Websocket connections |
| WEBSOCKET_MAX_MSG_LEN | "4096" | Maximum Websocket message length |
| WEBSOCKET_TIMEOUT | "10" | Websocket timeout |
| PUSH_ENABLE | "getui" | Push notification enable status |
| GETUI_PUSH_URL | [Generated URL] | GeTui Push Notification URL |
| GETUI_MASTER_SECRET | [User Defined] | GeTui Master Secret |
| GETUI_APP_KEY | [User Defined] | GeTui Application Key |
| GETUI_INTENT | [User Defined] | GeTui Push Intent |
| GETUI_CHANNEL_ID | [User Defined] | GeTui Channel ID |
| GETUI_CHANNEL_NAME | [User Defined] | GeTui Channel Name |
| FCM_SERVICE_ACCOUNT | "x.json" | FCM Service Account |
| JPNS_APP_KEY | [User Defined] | JPNS Application Key |
| JPNS_MASTER_SECRET | [User Defined] | JPNS Master Secret |
| JPNS_PUSH_URL | [User Defined] | JPNS Push Notification URL |
| JPNS_PUSH_INTENT | [User Defined] | JPNS Push Intent |
| MANAGER_USERID_1 | "openIM123456" | Administrator ID 1 |
| MANAGER_USERID_2 | "openIM654321" | Administrator ID 2 |
| MANAGER_USERID_3 | "openIMAdmin" | Administrator ID 3 |
| NICKNAME_1 | "system1" | Nickname 1 |
| NICKNAME_2 | "system2" | Nickname 2 |
| NICKNAME_3 | "system3" | Nickname 3 |
| MULTILOGIN_POLICY | "1" | Multi-login Policy |
| CHAT_PERSISTENCE_MYSQL | "true" | Chat Persistence in MySQL |
| MSG_CACHE_TIMEOUT | "86400" | Message Cache Timeout |
| GROUP_MSG_READ_RECEIPT | "true" | Group Message Read Receipt Enable |
| SINGLE_MSG_READ_RECEIPT | "true" | Single Message Read Receipt Enable |
| RETAIN_CHAT_RECORDS | "365" | Retain Chat Records (in days) |
| CHAT_RECORDS_CLEAR_TIME | [Cron Expression] | Chat Records Clear Time |
| MSG_DESTRUCT_TIME | [Cron Expression] | Message Destruct Time |
| SECRET | "${PASSWORD}" | Secret Key |
| TOKEN_EXPIRE | "90" | Token Expiry Time |
| FRIEND_VERIFY | "false" | Friend Verification Enable |
| IOS_PUSH_SOUND | "xxx" | iOS |
### 2.20. <a name='PrometheusConfiguration-1'></a>Prometheus Configuration
This section involves configuring Prometheus, including enabling/disabling it and setting up ports for various services.
#### 2.20.1. <a name='GeneralConfiguration'></a>General Configuration
| Parameter | Example Value | Description |
| ------------------- | ------------- | ----------------------------- |
| `PROMETHEUS_ENABLE` | "false" | Whether to enable Prometheus. |
#### 2.20.2. <a name='Service-SpecificPrometheusPorts'></a>Service-Specific Prometheus Ports
| Service | Parameter | Default Port Value | Description |
| ------------------------ | ------------------------ | ---------------------------- | -------------------------------------------------- |
| User Service | `USER_PROM_PORT` | '20110' | Prometheus port for the User service. |
| Friend Service | `FRIEND_PROM_PORT` | '20120' | Prometheus port for the Friend service. |
| Message Service | `MESSAGE_PROM_PORT` | '20130' | Prometheus port for the Message service. |
| Message Gateway | `MSG_GATEWAY_PROM_PORT` | '20140' | Prometheus port for the Message Gateway. |
| Group Service | `GROUP_PROM_PORT` | '20150' | Prometheus port for the Group service. |
| Auth Service | `AUTH_PROM_PORT` | '20160' | Prometheus port for the Auth service. |
| Push Service | `PUSH_PROM_PORT` | '20170' | Prometheus port for the Push service. |
| Conversation Service | `CONVERSATION_PROM_PORT` | '20230' | Prometheus port for the Conversation service. |
| RTC Service | `RTC_PROM_PORT` | '21300' | Prometheus port for the RTC service. |
| Third Service | `THIRD_PROM_PORT` | '21301' | Prometheus port for the Third service. |
| Message Transfer Service | `MSG_TRANSFER_PROM_PORT` | '21400, 21401, 21402, 21403' | Prometheus ports for the Message Transfer service. |

8
docs/contrib/install_docker.md
Unescape View File

@ -1,5 +1,13 @@
<!-- vscode-markdown-toc -->
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->
# Install Docker
The installation command is as follows:
```bash

Write Preview
Loading…
Cancel
Save