feat: translate to English

Author: dsx137

i18n/en/docusaurus-plugin-content-docs-guides/current.json

@@ -8,8 +8,8 @@
     "description": "The label for category 'Quick Start' in sidebar 'tutorialSidebar'"
   },
   "sidebar.tutorialSidebar.category.快速部署": {
-    "message": "Quick Deploy",
-    "description": "The label for category 'Quick Deploy' in sidebar 'tutorialSidebar'"
+    "message": "Quick Deployment",
+    "description": "The label for category 'Quick Deployment' in sidebar 'tutorialSidebar'"
   },
   "sidebar.tutorialSidebar.category.解决方案": {
     "message": "Solutions",

i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/_category_.json

@@ -1,6 +1,6 @@
 {
   "position": 2,
-  "label": "Quick Deploy",
+  "label": "Quick Deployment",
   "collapsible": true,
   "collapsed": true
 }

i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/prometheus0.png

@@ -5,63 +5,70 @@ sidebar_position: 5
 
 
 
-# IMServer Source Code Cluster Deployment Guide (Same LAN)
+# OpenIMServer Source Code Cluster Deployment Guide on the Same Internal Network
 
-This guide uses machines A and B (with internal IPs `IP_A` and `IP_B`) as an example. They are located in the same LAN environment, used for deploying the clustered IM Server and Nginx.
-Assuming you have already deployed Redis cluster, MongoDB sharded cluster, Kafka cluster, and Etcd cluster at the following addresses:
-- **Redis Cluster**: `redisAddr1`, `redisAddr2`, `redisAddr3`
-- **MongoDB Cluster**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3`
-- **Kafka Cluster**: `kafkaAddr1`, `kafkaAddr2`, `kafkaAddr3`
-- **Etcd Cluster**: `etcdAddr1`, `etcdAddr2`, `etcdAddr3`
+This guide uses machines A and B (with internal IPs `IP_A` and `IP_B`) as examples. They are located in the same internal network and are used to deploy clustered OpenIMServer and Nginx.
+Assume that you have already deployed a Redis cluster, MongoDB sharded cluster, Kafka cluster, and Etcd cluster with the following addresses:
+- **Redis cluster addresses**: `redisAddr1`, `redisAddr2`, `redisAddr3`
+- **MongoDB cluster addresses**: `mongoAddr1`, `mongoAddr2`, `mongoAddr3`
+- **Kafka cluster addresses**: `kafkaAddr1`, `kafkaAddr2`, `kafkaAddr3`
+- **Etcd cluster addresses**: `etcdAddr1`, `etcdAddr2`, `etcdAddr3`
 
-These components should be deployed on three or more nodes to ensure high availability and load balancing.
+It is recommended to deploy these components on three or more nodes to ensure high availability and load balancing.
 
-Additionally, MinIO's internal access address is configured as `your_minio_internal_address`, and the external access address is `your_minio_external_address`.
-Machines A and B, as well as the component clusters, have internal network connectivity. Both machines A and B also have public IPs.
+In addition, MinIO is configured with `your_minio_internal_address` for internal access and `your_minio_external_address` for external access.
+Machines A and B, as well as the component clusters, must be reachable over the internal network, and both A and B must have public IPs.
 
 ### Table of Contents
 
 1. [Prerequisites](#prerequisites)
-2. [Clone Repository](#1-clone-repository)
+2. [Clone the Repository](#1-clone-the-repository)
 3. [Modify Configuration](#2-modify-configuration)
 4. [Configure Nginx](#3-configure-nginx)
-5. [Set Up DNS](#4-set-up-dns)
+5. [Configure DNS](#4-configure-dns)
 6. [Start Services](#5-start-services)
 
 ### Prerequisites
 
-Ensure the following components are properly deployed and running:
+Ensure that the following components are already deployed and running correctly:
 
-- **Redis Cluster**
-- **MongoDB Sharded Cluster**
-- **Kafka Cluster**
-- **Etcd Cluster**
-- **MinIO Service**
+- **Redis cluster**
+- **MongoDB sharded cluster**
+- **Kafka cluster**
+- **Etcd cluster**
+- **MinIO service**
 
-### 1. Clone Repository
+> This document only covers deploying two OpenIMServer business nodes and Nginx. It does not include the deployment of the Redis / MongoDB / Kafka / Etcd clusters themselves. If you currently only have two empty machines, complete those external component clusters first before continuing.
 
-On both machines (A and B), run the following commands to clone the `open-im-server` repository:
+### 1. Clone the Repository
+
+Run the following commands on both machines (A and B) to clone the OpenIMServer repository and switch to the latest official release tag marked with the green **Latest** badge on GitHub Releases:
 
 ```bash
 git clone https://github.com/openimsdk/open-im-server
 cd open-im-server
+git fetch --tags
+LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)")
+git checkout "$LATEST_STABLE_TAG"
 ```
 
+> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. It is recommended that both machines use the same stable tag. If you need a fixed version such as `v3.8.3-patch.12`, run `git checkout v3.8.3-patch.12` on both machines.
+
 ### 2. Modify Configuration
 
-On both machines A and B, modify the configuration files as follows to ensure all components are correctly connected. All address fields use the inline list format `address: [addr1, addr2, addr3]`.
+On machines A and B, modify the configuration files as follows so that all components connect correctly. All address fields use the single-line list format `address: [addr1, addr2, addr3]`.
 
 #### 2.1 Kafka Configuration
 
-Edit the `open-im-server/config/kafka.yml` file, setting the `address` field to the Kafka cluster address list:
+Edit `open-im-server/config/kafka.yml` and set the `address` field to the Kafka cluster address list:
 
 ```yaml
 address: [kafkaAddr1, kafkaAddr2, kafkaAddr3]
 ```
 
 #### 2.2 MinIO Configuration
 
-Edit the `open-im-server/config/minio.yml` file, setting `internalAddress` and `externalAddress`:
+Edit `open-im-server/config/minio.yml` and set `internalAddress` and `externalAddress`:
 
 ```yaml
 internalAddress: your_minio_internal_address
@@ -70,15 +77,15 @@ externalAddress: your_minio_external_address
 
 #### 2.3 MongoDB Configuration
 
-Edit the `open-im-server/config/mongodb.yml` file, setting the `address` field to the MongoDB cluster address list:
+Edit `open-im-server/config/mongodb.yml` and set the `address` field to the MongoDB cluster address list:
 
 ```yaml
 address: [mongoAddr1, mongoAddr2, mongoAddr3]
 ```
 
 #### 2.4 Etcd Configuration
 
-Edit the `open-im-server/config/discovery.yml` file, setting the `etcd.address` field to the Etcd cluster address list:
+Edit `open-im-server/config/discovery.yml` and set `etcd.address` to the Etcd cluster address list:
 
 ```yaml
 etcd:
@@ -87,7 +94,7 @@ etcd:
 
 #### 2.5 Redis Configuration
 
-Edit the `open-im-server/config/redis.yml` file, setting the `address` field to the Redis cluster address list and enabling cluster mode:
+Edit `open-im-server/config/redis.yml`, set `address` to the Redis cluster address list, and enable cluster mode:
 
 ```yaml
 address: [redisAddr1, redisAddr2, redisAddr3]
@@ -96,9 +103,9 @@ clusterMode: true
 
 ### 3. Configure Nginx
 
-Deploy `nginx` on both machines A and B using the following configuration. Make sure to replace with your actual domain name, SSL certificate path, and SSL key path.
+Deploy `nginx` on machines A and B using the following configuration. Make sure to replace it with your actual domain, SSL certificate path, and SSL private key path.
 
-> 🚀 **Tip**: Make sure to replace with your actual domain name, SSL certificate path, and SSL key.
+> 🚀 **Tip**: Be sure to replace the example domain, SSL certificate path, and SSL key path with your actual values.
 
 ```nginx
 events {
@@ -113,7 +120,7 @@ http {
     }
 
     upstream im_api {
-        # IM API server addresses — specify multiple based on your deployment
+        # OpenIMServer API addresses; add more upstreams if needed
         server IP_A:10002;
         server IP_B:10002;
     }
@@ -123,9 +130,9 @@ http {
         server_name  yourhost.com;  # Replace with your domain
 
         ssl_certificate     /usr/local/nginx/conf/ssl/your_host_bundle.pem;  # Replace with your certificate path
-        ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key;        # Replace with your certificate key path
+        ssl_certificate_key /usr/local/nginx/conf/ssl/your_host.key;        # Replace with your private key path
 
-        location ^~/api/ {
+        location ^~ /api/ {
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "Upgrade";
@@ -145,7 +152,7 @@ http {
         }
     }
 
-    # Optional: HTTP to HTTPS redirect
+    # Optional: redirect HTTP to HTTPS
     server {
         listen 80;
         server_name yourhost.com;  # Replace with your domain
@@ -155,23 +162,32 @@ http {
 }
 ```
 
-Add this configuration to your `nginx` config file and reload to apply:
+Add this configuration to the Nginx configuration file and reload it to apply the changes:
 
-### 4. Set Up DNS
+### 4. Configure DNS
 
 Point your domain `yourhost.com` to the public IP addresses of machines A and B.
 
 ### 5. Start Services
 
-On both machines (A and B), run the following commands in the `open-im-server` directory to build and start the services:
+Run the following commands in the `open-im-server` directory on both machines (A and B) to build and start the services:
 
-For users in China, it is recommended to set a Go proxy:
+For users in Mainland China, setting a Go proxy is recommended:
 ```
 $ go env -w GO111MODULE=on
 $ go env -w GOPROXY=https://goproxy.cn,direct
 ```
 
 #### 5.1 Build
+
+Before the first execution on each machine, it is recommended to run:
+
+```bash
+bash bootstrap.sh
+```
+
+This step installs `mage`. If `mage` is already installed on your machine, you can skip it.
+
 ```bash
 mage
 ```
@@ -183,8 +199,8 @@ mage start
 ```
 
 
-## **FAQ / Important Notes**
+## **FAQ / Notes**
 
-1. When deploying `Kafka`, you need to modify the Kafka advertised port. If using the `docker-compose.yml` from `open-im-server`, modify `service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS` where `EXTERNAL` should be set to the address for accessing the Kafka component. For other deployment methods, modify accordingly.
-   Example: `KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://192.168.2.36:19094`.
-2. Multi-machine deployments require clock synchronization across machines for services to run correctly. For example, the `token` signing process allows a maximum clock skew of `5 seconds` between machines.
+1. When deploying `kafka`, you need to modify the Kafka advertised port. If you use `docker-compose.yml` from `open-im-server`, change the `EXTERNAL` listener in `service.kafka.environment.KAFKA_CFG_ADVERTISED_LISTENERS` to the address used to access the `kafka` component. If you use another deployment method, adjust it accordingly.
+   For example: `KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://192.168.2.36:19094`.
+2. In multi-machine deployment, the clocks of all machines must stay synchronized, or services may fail. For example, token issuing only tolerates clock drift within `5s`.

i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.assets/rpc0.png

@@ -3,26 +3,32 @@ title: 'Docker Deployment'
 sidebar_position: 2
 
 ---
-## 1. Prerequisites 🌍
-For server hardware, software, operating system, and component requirements, please refer to [this document](./env-comp).
+## 1. Environment Preparation 🌍
+For server hardware, software, operating system, and dependent components, please refer to [this document](./env-comp).
 
-## 2. Deploy IMServer
+## 2. Deploy OpenIMServer
 ### 2.1 Clone the Repository 🗂️
 
+Use the latest official release tag marked with the green **Latest** badge on the GitHub Releases page. Do not sort tags manually, and do not use pre-release versions such as alpha or rc.
+
 ```bash
 git clone https://github.com/openimsdk/openim-docker && cd openim-docker
+git fetch --tags
+LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)")
+git checkout "$LATEST_STABLE_TAG"
+echo "using openim-docker stable release tag: $LATEST_STABLE_TAG"
 ```
 
-### 2.2 Modify Configuration 🔧
+> Here, `latest` means the latest official release marked with the green **Latest** badge on GitHub Releases. It does not include alpha, beta, rc, or other pre-releases. `main` is the development branch and should not be used directly in production.
+
+### 2.2 Configuration Changes 🔧
 
-- Edit the `.env` file to configure the MinIO external IP for sending images, videos, and files. Replace `your-server-ip` with your server's public IP address:
+- Edit `.env` and configure the MinIO external IP to support image and file sending. Replace `your-server-ip` with your server's public IP.
 
   ```plaintext
   MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005"
   ```
 
-
-
 ### 2.3 Start Services 🚀
 
 - Start services:
@@ -31,6 +37,11 @@ git clone https://github.com/openimsdk/openim-docker && cd openim-docker
 docker compose up -d
 ```
 
+> The first run pulls large images and may take some time. After startup, wait `30-60s` before running health checks or API verification.
+
+> This document assumes a **clean environment**. If the machine already has containers with the same names such as `mongo`, `redis`, `kafka`, `etcd`, `minio`, `openim-server`, or `openim-chat`, `docker compose up -d` will fail because of `container_name` conflicts. In that case, stop and remove those containers first, or reuse the existing components after adjusting configuration.
+
+> If startup shows warnings such as missing `ETCD_USERNAME`, `ETCD_PASSWORD`, `KAFKA_USERNAME`, or `KAFKA_PASSWORD`, and you have not enabled authentication for those components, these warnings can usually be ignored.
 
 - Stop services:
 
@@ -44,17 +55,34 @@ docker compose down
 docker logs -f openim-server
 ```
 
-## 3. Quick Verification ⚡
+### 2.4 Monitoring & Alerting (Optional)
+
+If you also want to start `Prometheus`, `Alertmanager`, `Grafana`, and `node-exporter`, run:
+
+```bash
+docker compose --profile m up -d
+```
+
+Default ports follow the current `.env`. Common values are:
+
+- `19090`: Prometheus
+- `19093`: Alertmanager
+- `13000`: Grafana
+- `19100`: node-exporter
+
+## 3. Quick Experience ⚡
 
-To quickly test the core capabilities of OpenIMSDK and verify your deployment, refer to [Quick Verification](./quickTestServer).
+To quickly experience core OpenIMSDK capabilities and verify whether OpenIMServer / ChatServer deployment is working, refer to [Quick Verification](./quickTestServer).
 
+> Additional note for the current project layout: if you deploy from the two source repositories `open-im-server` and `chat`, `open-im-server/docker-compose.yml` is mainly used for dependency components, and ChatServer still needs to be started with `mage start` in the `chat` directory. See [Source Code Deployment](./imSourceCodeDeployment).
 
 ## 4. FAQ
 
-### Troubleshooting Unhealthy Status
-1. Run `docker exec -it openim-server mage check` and verify if it has been running for more than one minute.
-2. Run `docker logs -f openim-server` to view logs.
+### Troubleshooting `unhealthy`
+1. Run `docker exec -it openim-server mage check` and confirm whether the state lasts longer than one minute.
+2. Run `docker logs -f openim-server` to inspect logs.
+3. If `openim-chat` briefly reports `connect: connection refused` during startup, wait `30-60s` and check again. This is usually a startup ordering issue while `openim-server` is still becoming ready.
 
-### Modifying Configuration
-Editing configuration files inside the `config` directory within the container has no effect!
-You must use environment variables to modify configuration. Refer to the [Environment Variable Configuration Guide](https://github.com/openimsdk/openim-docker/issues/136).
+### Configuration Changes
+Editing files under the container `config` directory does not work.
+Configuration changes must be made through environment variables. See the [environment variable guide](https://github.com/openimsdk/openim-docker/issues/136).

i18n/en/docusaurus-plugin-content-docs-guides/current/gettingStarted/cluster.md

@@ -5,33 +5,45 @@ sidebar_position: 1
 
 # 🧩 Platform & Component Requirements
 
----
-
-## 🌐 Operating System & Hardware
-
-| Requirement | Details |
-| --- | --- |
-| **Operating System** | Linux, Windows, macOS |
-| **Hardware Resources** | 4-core CPU, 8 GB RAM, 10 Mbps bandwidth, 100 GB disk minimum |
-
+Applies to the OpenIMServer and ChatServer deployment documents under `docs/guides/gettingStarted`.
 
+---
 
-
-## 🌐 Software
-| Software | Details |
-| --- | --- |
-| **Golang** | v1.21 or higher, [Installation Guide](https://go.dev/learn/) |
-| **Docker** | v24.0.5 or higher, [Installation Guide](https://www.docker.com/get-started/) |
-| **Git** | v2.17.1 or higher, [Installation Guide](https://git-scm.com/downloads) |
-
-## 💾 Component Requirements
-
-| Component | Recommended Version |
-| --- | --- |
-| **MongoDB** | v7.0 |
-| **Redis** | v7.0.0 |
-| **Etcd** | v3.5.13 |
-| **Kafka** | v3.5.1 |
-| **MinIO** | RELEASE.2024-01-11T07-46-16Z |
+## 1. Terminology
+
+- **OpenIMSDK**: The overall project name, including OpenIMClientSDK and OpenIMServer.
+- **OpenIMClientSDK**: The client SDK.
+- **OpenIMServer**: The IM core server.
+- **ChatServer**: The business extension server. This documentation no longer uses `Chat` as a standalone product name.
+- **APP Administrator**: The backend management role that calls management APIs such as `10009`.
+- **APP Business Server**: The application-side server that calls business extension APIs such as `10008`.
+
+## 2. Version and Branch Strategy
+
+- `main`: The development branch for unreleased changes in continuous integration. It is not recommended for production.
+- `vX.Y.Z...`: Stable release version naming.
+- For production, prefer the latest official release marked with the green **Latest** badge on the GitHub Releases page.
+- If you need reproducible troubleshooting, rollback, or multi-environment consistency, pin an explicit stable release tag.
+
+## 3. Environment Requirements
+
+| Item | Details | Notes |
+| --- | --- | --- |
+| Operating system | Linux | Officially uses `ubuntu 22.04`; `Debian 13` has also been verified to work |
+| Hardware resources | 8 CPU cores, 16 GB RAM, 10 Mbps bandwidth, 1 TB disk | Estimated for 100k registered users, 10% daily online ratio, 50k-member large groups, and 600 messages per second; requires a public IP |
+| CPU architecture | `x86_64` | ARM requires separate verification |
+| Golang | `v1.22.7` or higher | [Installation reference](https://go.dev/learn/) |
+| Docker | `v24.0.5` or higher | Must include `compose` support |
+| Git | `v2.17.1` or higher | [Installation reference](https://git-scm.com/downloads) |
+
+## 4. External Component Requirements
+
+| Component | Recommended Version | Supported Modes in OpenIMServer | ChatServer Access Mode | Cloud Support / Notes |
+| --- | --- | --- | --- | --- |
+| MongoDB | `v7.0` | `standalone`, `replicaSet` | `address` or `uri` | Supported; for replica sets, `uri` is preferred |
+| Redis | `v7.0.0` | `standalone`, `cluster`, `sentinel` | `standalone`, `clusterMode` | Supported; `sentinel` is explicitly supported only in OpenIMServer config |
+| Etcd | `v3.5.13` | Single node, multi-node cluster | Multi-address access | No managed cloud support |
+| Kafka | `v3.5.1` | Single node, distributed cluster | Not directly used by ChatServer | Supported; required topics must be created in advance |
+| MinIO | `RELEASE.2024-01-11T07-46-16Z` | Single node | Not directly used by ChatServer | Can be replaced with S3-compatible storage such as `COS`, `OSS`, `Kodo`, or `AWS S3` |
 
 ---