docs: add openim cluster helm chart (#1291)

* docs: add openim cluster helm chart Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * docs: add openim scripts deployment system Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * docs: add all openim helm chart deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * docs: add all openim helm chart deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim install scripts docs Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim kubernetes deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim kubernetes deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim kubernetes deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim kubernetes deployment Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * fix: openim images version Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * fix: make image Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim helm charts Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim helm charts Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> * feat: add openim config docs Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com> --------- Signed-off-by: Xinwei Xiong(cubxxw) <3293172751nss@gmail.com>
2026-04-28 06:19:20 +08:00 · 2023-10-30 10:16:37 +08:00
parent 726f14fd40
commit a4b28c9523
184 changed files with 5659 additions and 1649 deletions
@@ -0,0 +1,353 @@
+# OpenIM System: Setup and Usage Guide
+
+<!-- vscode-markdown-toc -->
+* 1. [1. Introduction](#Introduction)
+* 2. [2. Prerequisites (Requires root permissions)](#PrerequisitesRequiresrootpermissions)
+* 3. [3. Create `openim-api` systemd unit template file](#Createopenim-apisystemdunittemplatefile)
+* 4. [4. Copy systemd unit template file to systemd config directory (Requires root permissions)](#CopysystemdunittemplatefiletosystemdconfigdirectoryRequiresrootpermissions)
+* 5. [5. Start systemd service](#Startsystemdservice)
+
+
+##  0. <a name='Introduction'></a>0. Introduction
+
+Systemd is the default service management form for the latest Linux distributions, replacing the original init.
+
+The OpenIM system is a comprehensive suite of services tailored to address a wide variety of messaging needs. This guide will walk you through the steps of setting up the OpenIM system services and provide insights into its usage.
+
+**Prerequisites:**
+
+ A Linux server with necessary privileges.
+ Ensure you have `systemctl` installed and running.
+
+
+##  1. <a name='Deployment'></a>1. Deployment
+
+1. **Retrieve the Installation Script**:
+
+   Begin by obtaining the OpenIM installation script which will be utilized to deploy the entire OpenIM system.
+
+2. **Install OpenIM**:
+
+   To install all the components of OpenIM, run:
+
+   ```bash
+   ./scripts/install/install.sh -i  
+   ```
+
+   or
+
+   ```bash
+   ./scripts/install/install.sh --install  
+   ```
+
+   This will initiate the installation process for all OpenIM components.
+
+3. **Check the Status**:
+
+   Post installation, it is good practice to verify if all the services are running as expected:
+
+   ```bash
+   systemctl status openim.target
+   ```
+
+   This will list the status of all related services of OpenIM.
+
+**Maintenance & Management:**
+
+1. **Checking Individual Service Status**:
+
+   You can monitor the status of individual services with the following command:
+
+   ```bash
+   systemctl status <service-name>
+   ```
+
+   For instance:
+
+   ```bash
+   systemctl status openim-api.service
+   ``
+
+2. **Starting and Stopping Services**:
+
+   If you wish to start or stop any specific service, you can do so with `systemctl start` or `systemctl stop` followed by the service name:
+
+   ```bash
+   systemctl start openim-api.service
+   systemctl stop openim-api.service
+   ```
+
+3. **Uninstalling OpenIM**:
+
+   In case you wish to remove the OpenIM components from your server, utilize:
+
+   ```bash
+   ./scripts/install/install.sh -u
+   ```
+
+   or
+
+   ```bash
+   ./scripts/install/install.sh --uninstall
+   ```
+
+   Ensure you take a backup of any important data before executing the uninstall command.
+
+4. **Logs & Troubleshooting**:
+
+   Logs play a pivotal role in understanding the system's operation and troubleshooting any issues. OpenIM logs can typically be found in the directory specified during installation, usually `${OPENIM_LOG_DIR}`.
+
+   Always refer to the logs when troubleshooting. Look for any error messages or warnings that might give insights into the issue at hand.
+
+
+**Note:**
+
+ `openim-api.service`: Manages the main API gateways for OpenIM communication.
+ `openim-crontask.service`: Manages scheduled tasks and jobs.
+ `openim-msggateway.service`: Takes care of message gateway operations.
+ `openim-msgtransfer.service`: Handles message transfer functionalities.
+ `openim-push.service`: Responsible for push notification services.
+ `openim-rpc-auth.service`: Manages RPC (Remote Procedure Call) for authentication.
+ `openim-rpc-conversation.service`: Manages RPC for conversations.
+ `openim-rpc-friend.service`: Handles RPC for friend-related operations.
+ `openim-rpc-group.service`: Manages group-related RPC operations.
+ `openim-rpc-msg.service`: Takes care of message RPCs.
+ `openim-rpc-third.service`: Deals with third-party integrations using RPC.
+ `openim-rpc-user.service`: Manages user-related RPC operations.
+ `openim.target`: A target that bundles all the above services for collective operations.
+
+
+**Viewing Logs with `journalctl`:**
+
+`systemctl` services usually log their output to the systemd journal, which you can access using the `journalctl` command.
+
+1. **View Logs for a Specific Service**:
+
+   To view the logs for a particular service, you can use:
+
+   ```bash
+   journalctl -u <service-name>
+   ```
+
+   For example, to see the logs for the `openim-api.service`, you would use:
+
+   ```bash
+   journalctl -u openim-api.service
+   ```
+
+2. **Filtering Logs**:
+
+   + By Time
+
+     : If you wish to see logs since a specific time:
+
+     ```bash
+     journalctl -u openim-api.service --since "2023-10-28 12:00:00"
+     ```
+
+   + Most Recent Logs
+
+     : To view the most recent logs, you can combine 
+`tail` functionality with `journalctl`:
+
+     ```bash
+     journalctl -u openim-api.service -n 100
+     ```
+
+3. **Continuous Monitoring of Logs**:
+
+   To see new log messages in real-time, you can use the `-f` flag, which mimics the behavior of `tail -f`:
+
+   ```bash
+   journalctl -u openim-api.service -f
+   ```
+
+### Continued Maintenance:
+
+1. **Regularly Check Service Status**:
+
+   It's good practice to routinely verify that all services are active and running. This can be done with:
+
+   ```bash
+   systemctl status openim-api.service openim-push.service openim-rpc-group.service openim-crontask.service openim-rpc-auth.service openim-rpc-msg.service openim-msggateway.service openim-rpc-conversation.service openim-rpc-third.service openim-msgtransfer.service openim-rpc-friend.service openim-rpc-user.service
+   ```
+
+2. **Update Services**:
+
+   Periodically, there might be updates or patches to the OpenIM system or its components. Make sure you keep the system updated. After updating any service, always reload the daemon and restart the service:
+
+   ```bash
+   systemctl daemon-reload
+   systemctl restart openim-api.service
+   ```
+
+3. **Backup Important Data**:
+
+   Regularly backup any configuration files, user data, and other essential data. This ensures that you can restore the system to a working state in case of failures.
+
+### Important `systemctl` and Logging Commands to Learn:
+
+1. **Start/Stop/Restart Services**:
+
+   ```bash
+   systemctl start <service-name>
+   systemctl stop <service-name>
+   systemctl restart <service-name>
+   ```
+
+2. **Enable/Disable Services**:
+
+   If you want a service to start automatically at boot:
+
+   ```bash
+   systemctl enable <service-name>
+   ```
+
+   To prevent it from starting at boot:
+
+   ```bash
+   systemctl disable <service-name>
+   ```
+
+3. **Check Failed Services**:
+
+   To quickly check if any service has failed:
+
+   ```bash
+   systemctl --failed
+   ```
+
+4. **Log Rotation**:
+
+   `journalctl` logs can grow large. To clear all archived journal entries, use:
+
+   ```bash
+   journalctl --vacuum-time=1d
+   ```
+
+
+**Advanced requirements:**
+
+- Convenient service runtime log recording for problem analysis
+- Service management logs
+- Option to restart upon abnormal exit
+
+The daemon does not meet these advanced requirements.
+
+`nohup` only logs the service's runtime outputs and errors.
+
+Only systemd can fulfill all of the above requirements.
+
+> The default logs are enhanced with timestamps, usernames, service names, PIDs, etc., making them user-friendly. You can view logs of abnormal service exits. Advanced customization is possible through the configuration files in `/lib/systemd/system/`.
+
+In short, systemd is the current mainstream way to manage backend services on Linux, so I've abandoned `nohup` in my new versions of bash scripts, opting instead for systemd.
+
+##  2. <a name='PrerequisitesRequiresrootpermissions'></a>Prerequisites (Requires root permissions)
+
+1. Configure `environment.sh` based on the comments.
+2. Create a data directory:
+
+```bash
+mkdir -p ${OPENIM_DATA_DIR}/{openim-api,openim-crontask}
+```
+
+3. Create a bin directory and copy `openim-api` and `openim-crontask` executable files:
+
+```bash
+source ./environment.sh
+mkdir -p ${OPENIM_INSTALL_DIR}/bin
+cp openim-api openim-crontask ${OPENIM_INSTALL_DIR}/bin
+```
+
+4. Copy the configuration files of `openim-api` and `openim-crontask` to the `${OPENIM_CONFIG_DIR}` directory:
+
+```bash
+mkdir -p ${OPENIM_CONFIG_DIR}
+cp openim-api.yaml openim-crontask.yaml ${OPENIM_CONFIG_DIR}
+```
+
+##  3. <a name='Createopenim-apisystemdunittemplatefile'></a> Create `openim-api` systemd unit template file
+
+For each OpenIM service, we will create a systemd unit template. Follow the steps below for each service:
+
+Run the following shell script to generate the `openim-api.service.template`:
+
+```bash
+source ./environment.sh
+cat > openim-api.service.template <<EOF
+[Unit]
+Description=OpenIM Server API
+Documentation=https://github.com/oepnimsdk/open-im-server/blob/master/init/README.md
+
+[Service]
+WorkingDirectory=${OPENIM_DATA_DIR}/openim-api
+ExecStart=${OPENIM_INSTALL_DIR}/bin/openim-api --config=${OPENIM_CONFIG_DIR}/openim-api.yaml
+Restart=always
+RestartSec=5
+StartLimitInterval=0
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+Following the above style, create the respective template files or generate them in bulk:
+
+First, make sure you've sourced the environment variables:
+
+```bash
+source ./environment.sh
+```
+
+Use the shell script to generate the systemd unit template for each service:
+
+```bash
+declare -a services=(
+"openim-api"
+... [other services]
+)
+
+for service in "${services[@]}"
+do
+   cat > $service.service.template <<EOF
+[Unit]
+Description=OpenIM Server - $service
+Documentation=https://github.com/oepnimsdk/open-im-server/blob/master/init/README.md
+
+[Service]
+WorkingDirectory=${OPENIM_DATA_DIR}/$service
+ExecStart=${OPENIM_INSTALL_DIR}/bin/$service --config=${OPENIM_CONFIG_DIR}/$service.yaml
+Restart=always
+RestartSec=5
+StartLimitInterval=0
+
+[Install]
+WantedBy=multi-user.target
+EOF
+done
+```
+
+##  4. <a name='CopysystemdunittemplatefiletosystemdconfigdirectoryRequiresrootpermissions'></a>Copy systemd unit template file to systemd config directory (Requires root permissions)
+
+Ensure you have root permissions to perform this operation:
+
+```bash
+for service in "${services[@]}"
+do
+   sudo cp $service.service.template /etc/systemd/system/$service.service
+done
+...
+```
+
+##  5. <a name='Startsystemdservice'></a>Start systemd service
+
+To start the OpenIM services:
+
+```bash
+for service in "${services[@]}"
+do
+   sudo systemctl daemon-reload 
+   sudo systemctl enable $service 
+   sudo systemctl restart $service
+done
+```
@@ -7,6 +7,7 @@
  - [Tag Management: The Cornerstone of Version Control](#tag-management-the-cornerstone-of-version-control)
  - [Release Management: A Guided Tour](#release-management-a-guided-tour)
  - [Milestones, Branching, and Addressing Major Bugs](#milestones-branching-and-addressing-major-bugs)
+  - [Version Skew Policy](#version-skew-policy)
  - [Applying Principles: A Git Workflow Example](#applying-principles-a-git-workflow-example)
  - [Docker Images Version Management](#docker-images-version-management)

@@ -77,6 +78,97 @@ When dealing with major bugs, we selectively merge the fix into the affected ver

 We reinforce our approach to branch management and versioning with stringent testing protocols. Automated tests and code review sessions form vital components of maintaining a robust and reliable codebase.

+## Version Skew Policy
+
+This document describes the maximum version skew supported between various openim components. Specific cluster deployment tools may place additional restrictions on version skew.
+
+
+### Supported version skew
+
+In highly-available (HA) clusters, the newest and oldest `openim-api` instances must be within one minor version.
+
+### OpenIM Versioning, Branching, and Tag Strategy
+
+Similar to Kubernetes, OpenIM has a strict versioning, branching, and tag strategy to ensure compatibility among its various services and components. This document outlines the policies, especially focusing on the version skew supported between OpenIM's components. Given that the current version is v3.3, the policy references will be centered around this version.
+
+#### Supported Version Skew
+
+##### openim-api
+
+In highly-available (HA) clusters, the newest and oldest `openim-api` instances must be within one minor version.
+
+Example:
+
+ Newest `openim-api` is at v3.3
+ Other `openim-api` instances are supported at v3.3 and v3.2
+
+##### openim-rpc-* Components
+
+All `openim-rpc-*` components (e.g., `openim-rpc-auth`, `openim-rpc-conversation`, etc.) should adhere to the following rules:
+
+1. They must not be newer than `openim-api`.
+2. They may be up to one minor version older than `openim-api`.
+
+Example:
+
+ `openim-api` is at v3.3
+ All `openim-rpc-*` components are supported at v3.3 and v3.2
+
+Note: If version skew exists between `openim-api` instances in an HA cluster, this narrows the allowed `openim-rpc-*` components versions.
+
+##### Other OpenIM Services
+
+Other OpenIM services such as `openim-cmdutils`, `openim-crontask`, `openim-msggateway`, etc. should adhere to the following rules:
+
+1. These services must not be newer than `openim-api`.
+2. They are expected to match the `openim-api` minor version but may be up to one minor version older (to allow live upgrades).
+
+Example:
+
+ `openim-api` is at v3.3
+ `openim-msggateway`, `openim-cmdutils`, and other services are supported at v3.3 and v3.2
+
+#### Supported Component Upgrade Order
+
+The version skew policy has implications on the order in which components should be upgraded. Below is the recommended order to transition an existing cluster from version v3.2 to v3.3:
+
+##### openim-api
+
+Pre-requisites:
+
+1. In a single-instance cluster, the existing `openim-api` instance is v3.2.
+2. In an HA cluster, all `openim-api` instances are at v3.2 or v3.3.
+3. All `openim-rpc-*` and other OpenIM services communicating with this server are at version v3.2.
+
+Upgrade Procedure:
+
+1. Upgrade `openim-api` to v3.3.
+
+##### openim-rpc-* Components
+
+Pre-requisites:
+
+1. The `openim-api` instances these components communicate with are at v3.3.
+
+Upgrade Procedure:
+
+2. Upgrade all `openim-rpc-*` components to v3.3.
+
+##### Other OpenIM Services
+
+Pre-requisites:
+
+1. The `openim-api` instances these services communicate with are at v3.3.
+
+Upgrade Procedure:
+
+2. Upgrade other OpenIM services such as `openim-msggateway`, `openim-cmdutils`, etc., to v3.3.
+
+#### Conclusion
+
+Just like Kubernetes, it's essential for OpenIM to have a strict versioning and upgrade policy to ensure seamless operation and compatibility among its various services. Adhering to the policies outlined above will help in achieving this goal.
+
+
 ## Applying Principles: A Git Workflow Example

 The workflow to address a bug fix might follow these steps: