feat: add readme docs

Signed-off-by: Xinwei Xiong(cubxxw-openim) <3293172751nss@gmail.com>
2 years ago · 0f2d9308e8
parent 36bb68e1e6
commit 0f2d9308e8
1 changed files with 226 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -109,7 +109,233 @@ Further enhancing your experience, we also provide an SDK client, wherein most c

    ✅  We have a large open source community called [OpenIMSDK](https://github.com/OpenIMSDK) that runs the core modules, we have an open source community called [openim-sigs](https://github.com/openim-sigs) to explore more IM-based infrastructure products.

+## :rocket: Quick Start

+You can quickly learn OpenIM engineering solutions,  all it takes is one simple command:
+
+```bash
+$ make demo
+```
+
+🤲 In order to facilitate the user experience, we have provided a variety of deployment solutions, you can choose your own deployment method according to the list below:
+
+<details>   <summary>Deploying with Docker Compose</summary>
+
+**1. Clone the project**
+
+```bash
+# choose what you need, We take branch 3.2 as an example
+$ BRANCH=release-v3.2
+$ git clone -b $BRANCH https://github.com/OpenIMSDK/Open-IM-Server openim && export openim=$(pwd)/openim && cd $openim
+```
+
+> **Note**
+> If you don't know OpenIM's versioning policy, 📚Read our release policy: https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md
+
+
+
+**2. Configure the config file**
+
+If you tried to get started quickly with `make demo`, then you know that our config file is generated by automation.
+
+You can use `make init` to quickly initialize a configuration file
+
+```bash
+$ make init
+$ git diff
+```
+
+Then feel free to modify your current config file,  you can also modify `/scripts/install/environment.sh` document template, `make init` is essentially rendering `environment.sh` template, and then through the `make init` to automatically generate a new configuration.
+
+If you only need to change the config file for a short time, or if you don't want to make any major changes in the future, you can modify the `.env file directly
+
+```bash
+USER=root 								#no need to modify
+PASSWORD=openIM123  					#A combination of 8 or more numbers and letters, this password applies to redis, mysql, mongo, as well as accessSecret in config/config.yaml
+ENDPOINT=http://127.0.0.1:10005 		#minio's external service IP and port, or use the domain name storage.xx.xx, the app must be able to access this IP and port or domain,
+API_URL=http://127.0.0.1:10002/object/ 	#the app must be able to access this IP and port or domain,
+DATA_DIR=./  							#designate large disk directory
+```
+
+3. **Deploy and start**
+
+> **Note**
+>
+> You can deploy either directly with `make install` or with `docker compose up`, the logic is the same
+
+```bash
+$ make install
+# OR
+$ docker-compose up
+```
+
+4. Check the service
+
+```bash
+$ make check
+```
+
+Looking at the command line at this point, there are two items in the output, checking for the start of the component port that OpenIM depends on, and the start of the OpenIM core component
+
+</details> 
+
+<details>  <summary>Compile from Source</summary>
+
+Ur need `Go 1.18` or higher version, and `make`.
+
+```bash
+$ go version; make --version
+```
+
+Version Details: https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md
+
+```bash
+# choose what you need
+$ BRANCH=release-v3.1
+$ git clone -b $BRANCH https://github.com/OpenIMSDK/Open-IM-Server openim && export openim=$(pwd)/openim && cd $openim && make build
+```
+
+Read about the [OpenIM Version Policy](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md)
+
+`make help` to help you see the instructions supported by OpenIM.
+
+All services have been successfully built as shown in the figure
+
+![Successful Compilation](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/images/build.png)
+
+</details>
+
+<details>  <summary>Component Configuration Instructions</summary>
+
+
+The config/config.yaml file has detailed configuration instructions for the storage components.
+
+- Zookeeper
+
+  - Used for RPC service discovery and registration, cluster support.
+
+    ```bash
+    zookeeper:
+      schema: openim                          #Not recommended to modify
+      address: [ 127.0.0.1:2181 ]             #address
+      username:                               #username
+      password:                               #password
+    ```
+
+- MySQL
+
+  - Used for storing users, relationships, and groups, supports master-slave database.
+
+    ```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                         #maximum time a connection can be reused (seconds)
+      logLevel: 4                             #log level 1=slient 2=error 3=warn 4=info
+      slowThreshold: 500                      #slow statement threshold (milliseconds)
+    ```
+
+- Mongo
+
+  - Used for storing offline messages, supports mongo sharded clusters.
+
+    ```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
+    ```
+
+- Redis
+
+  - Used for storing message sequence numbers, latest messages, user tokens, and mysql cache, supports cluster deployment.
+
+    ```bash
+    redis:
+      address: [ 127.0.0.1:16379 ]            #address
+      username:                               #username
+      password: openIM123                     #password
+    ```
+
+- Kafka
+
+  - Used for message queues, for message decoupling, supports cluster deployment.
+
+    ```bash
+    kafka:
+      username:                               #username
+      password:                               #password
+      addr: [ 127.0.0.1:9092 ]                #address
+      latestMsgToRedis:
+        topic: "latestMsgToRedis"
+      offlineMsgToMongo:
+        topic: "offlineMsgToMongoMysql"
+      msgToPush:
+        topic: "msqToPush"
+      msgToModify:
+        topic: "msgToModify"
+      consumerGroupID:
+        msgToRedis: redis
+        msgToMongo: mongo
+        msgToMySql: mysql
+        msgToPush: push
+        msgToModify: modify
+    ```
+
+</details>
+
+<details>  <summary>Start and Stop Services</summary>
+
+
+Start services
+
+```
+./scripts/start-all.sh;
+```
+
+Check services
+
+```
+./scripts/check_all.sh
+```
+
+Stop services
+
+```
+./scripts/stop-all.sh
+```
+
+</details> 
+
+<details>  <summary>Open IM Ports</summary>
+
+
+| TCP Port  | Description                                                  | Operation                                             |
+| --------- | ------------------------------------------------------------ | ----------------------------------------------------- |
+| TCP:10001 | ws protocol, message port such as message sending, pushing etc, used for client SDK | Port release or nginx reverse proxy, and firewall off |
+| TCP:10002 | api port, such as user, friend, group, message interfaces.   | Port release or nginx reverse proxy, and firewall off |
+| TCP:10005 | Required when choosing minio storage (openIM uses minio storage by default) | Port release or nginx reverse proxy, and firewall off |
+
+</details> 
+
+<details>  <summary>Open Chat Ports</summary>
+
+
+ chat warehouse: https://github.com/OpenIMSDK/chat 
+
+| TCP Port  | Description                                         | Operation                                             |
+| --------- | --------------------------------------------------- | ----------------------------------------------------- |
+| TCP:10008 | Business system, such as registration, login etc    | Port release or nginx reverse proxy, and firewall off |
+| TCP:10009 | Management backend, such as statistics, banning etc | Port release or nginx reverse proxy, and firewall off |
+
+</details>

 ## :link: Relationship Between APP and OpenIM