diff --git a/deployments/templates/openim.service b/deployments/templates/openim.service index 1206f01a6d..030e44c32c 100644 --- a/deployments/templates/openim.service +++ b/deployments/templates/openim.service @@ -1,6 +1,6 @@ [Unit] Description=${SERVER_NAME} for OpenIM -Documentation=https://github.com/openimsdk/open-im-server/blob/main/deployment/init/README.md +Documentation=https://github.com/openimsdk/open-im-server/blob/main/deployment/README.md [Service] WorkingDirectory=${OPENIM_DATA_DIR} diff --git a/deployments/templates/openim.target b/deployments/templates/openim.target new file mode 100644 index 0000000000..1d481ce31c --- /dev/null +++ b/deployments/templates/openim.target @@ -0,0 +1,7 @@ +[Unit] +Description=Unified target for OpenIM servers +Requires=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 +After=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 + +[Install] +WantedBy=multi-user.target diff --git a/docs/contrib/install-openim-linux-system.md b/docs/contrib/install-openim-linux-system.md new file mode 100644 index 0000000000..2956b02e42 --- /dev/null +++ b/docs/contrib/install-openim-linux-system.md @@ -0,0 +1,353 @@ +# OpenIM System: Setup and Usage Guide + + +* 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. 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. 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 + ``` + + 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 + ``` + + 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 + systemctl stop + systemctl restart + ``` + +2. **Enable/Disable Services**: + + If you want a service to start automatically at boot: + + ```bash + systemctl enable + ``` + + To prevent it from starting at boot: + + ```bash + systemctl disable + ``` + +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. 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. 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 < $service.service.template <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. 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 +``` diff --git a/scripts/install/environment.sh b/scripts/install/environment.sh index d4df45408a..6bf0e389bb 100755 --- a/scripts/install/environment.sh +++ b/scripts/install/environment.sh @@ -115,7 +115,7 @@ LAST_OCTET=$((LAST_OCTET + 1)) GRAFANA_NETWORK_ADDRESS=$(generate_ip) ###################### openim 配置 ###################### -# read: https://github.com/openimsdk/open-im-server/blob/main/deployment/init/README.md +# read: https://github.com/openimsdk/open-im-server/blob/main/deployment/README.md def "OPENIM_DATA_DIR" "/data/openim" def "OPENIM_INSTALL_DIR" "/opt/openim" def "OPENIM_CONFIG_DIR" "/etc/openim/config" diff --git a/scripts/install/install.sh b/scripts/install/install.sh index d4dbbb275c..915eef3f6b 100755 --- a/scripts/install/install.sh +++ b/scripts/install/install.sh @@ -89,6 +89,10 @@ function openim::install::install_openim() ${OPENIM_ROOT}/scripts/install/openim-rpc.sh openim::rpc::install || return 1 ${OPENIM_ROOT}/scripts/install/openim-api.sh openim::api::install || return 1 + openim::common::sudo "cp -r ${OPENIM_ROOT}/deployments/templates/openim.target /etc/systemd/system/openim.target" + openim::common::sudo "systemctl daemon-reload" + openim::common::sudo "systemctl restart openim.target" + openim::common::sudo "systemctl enable openim.target" openim::log::success "openim install success" } @@ -103,6 +107,11 @@ function openim::uninstall::uninstall_openim() ${OPENIM_ROOT}/scripts/install/openim-rpc.sh openim::rpc::uninstall || return 1 ${OPENIM_ROOT}/scripts/install/openim-api.sh openim::api::uninstall || return 1 + set +o errexit + openim::common::sudo "systemctl stop openim.target" + openim::common::sudo "systemctl disable openim.target" + openim::common::sudo "rm -f /etc/systemd/system/openim.target" + set -o errexit openim::log::success "openim uninstall success" } diff --git a/scripts/install/openim-man.sh b/scripts/install/openim-man.sh index 4cf8e385de..6dda4bfe10 100755 --- a/scripts/install/openim-man.sh +++ b/scripts/install/openim-man.sh @@ -48,7 +48,7 @@ OPENIM_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd) function openim::man::info() { cat <<- EOF Usage: - man openim-server # Display the man page for openim-server + man openim-server to see openim-server help # Display the man page for openim-server EOF } diff --git a/scripts/update-generated-docs.sh b/scripts/update-generated-docs.sh index bd2ebb268e..008cf63ed1 100755 --- a/scripts/update-generated-docs.sh +++ b/scripts/update-generated-docs.sh @@ -28,10 +28,10 @@ source "${OPENIM_ROOT}/hack/lib/init.sh" openim::golang::setup_env BINS=( - cmd/gendocs - cmd/genopenimdocs - cmd/genman - cmd/genyaml + gendocs + genopenimdocs + genman + genyaml ) make -C "${OPENIM_ROOT}" WHAT="${BINS[*]}"