Skip to main content

Docker Deployment for OpenIM

๐ŸŒ Environment Preparationโ€‹

๐Ÿ—‚๏ธ Repository Cloningโ€‹

git clone https://github.com/openimsdk/openim-docker

๐Ÿ”ง Configuration Modificationโ€‹

  • Modify the .env file to set up the external IP. If using a domain name, Nginx configuration is required.

    # Set the external access address for MinIO service (external IP or domain)
    MINIO_EXTERNAL_ADDRESS="http://external_ip:10005"
     # Set the external access address for Grafana service (external IP or domain)
      GRAFANA_URL="http://external_ip:13000/"

  • Please refer to the comments in the .env file for other configurations.

๐Ÿš€ Service Launchโ€‹

  • To start the service:
docker compose up -d
  • To stop the service:
docker compose down
  • To view logs:
docker logs -f openim-server
docker logs -f openim-chat

โšก Quick Experienceโ€‹

For a quick experience with OpenIM services, please visit the Quick Test Server Guide.

Below are the deployment processes for versions release-v3.6 and earlier:โ€‹

๐Ÿ›  Docker Deployment

1. Environment and Component Requirementsโ€‹

For server environment, system, and storage components, refer to this document.

2. Docker Deploymentโ€‹

2.1 Clone Repository and Initializeโ€‹

git clone https://github.com/openimsdk/openim-docker openim-docker && cd openim-docker && make init

๐Ÿ’ก Tips

If you obtained openim-docker not by cloning but by downloading a zip file, run the command find ./ -name "*.sh" | xargs chmod +x to grant script execution permissions.

2.2 Set OPENIM_IPโ€‹

๐Ÿ”” You must set OPENIM_IP, and it cannot be 127.0.0.1

# If the server has an external IP
export OPENIM_IP="external IP"

# If only providing internal network service
export OPENIM_IP="internal IP"

2.3 Start Service and View Logsโ€‹

docker compose up -d
docker ps
docker compose logs -f openim-chat
docker compose logs -f openim-server

3. Quick Verificationโ€‹

Please refer to the Quick Verification document.

4. Admin Panel and Monitoring Systemโ€‹

Please refer to the Admin Panel and Monitoring System document.

5. About Configuration Modificationโ€‹

This project has complex configuration items, primarily because some settings involve .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml multiple files. The explanation for modifying configuration items is divided into two parts: shared configuration items and other configuration items.

5.1 Shared Configuration Itemsโ€‹

Shared configuration items across .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml:

  1. MySQL/Mongo/Redis/Kafka/Zookeeper/MinIO ports and passwords;
  2. SECRET;
  3. API_OPENIM_PORT;
  4. OPENIM_IP;
  5. MINIO_PORT;
  6. GRAFANA_PORT

5.2 Modification Methodsโ€‹

For modifying shared configuration items, choose one of the following methods:

Method One: Regenerate all configurations

If a comprehensive update of configurations is needed, follow these steps:

  1. Delete existing configuration files: Remove openim-server/config/config.yaml and openim-chat/config/config.yaml files.
  2. Modify the .env file: Update relevant settings in the .env file.
  3. Regenerate configurations and restart service: Execute docker compose down ; docker compose up -d, which will regenerate configuration files based on the new settings in the .env file and restart the service.

Method Two: Modify multiple configuration files separately

If only a partial update is needed, follow these steps:

  1. Modify the .env file: Update relevant settings in the .env file.
  2. Manually update configuration files: According to modifications in the .env file, update corresponding settings in openim-server/config/config.yaml and openim-chat/config/config.yaml files

. 3. Special variable additional handling: If you modified OPENIM_IP, API_OPENIM_PORT, MINIO_PORT, GRAFANA_PORT, then you need to update the following configuration items in openim-server/config/config.yaml:

```yaml
object:
  apiURL: "http://$OPENIM_IP:$API_OPENIM_PORT"
  minio:
    endpoint: "http://$DOCKER_BRIDGE_GATEWAY:$MINIO_PORT"
    signEndpoint: "http://$OPENIM_IP:$MINIO_PORT"

grafanaUrl: http://$OPENIM_IP:$GRAFANA_PORT
```
  1. Restart the service: Execute docker compose down ; docker compose up -d to apply changes and restart the service.

5.3 Other Configuration Item Modificationโ€‹

For non-shared variables in .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml, you can individually modify these configuration items in the respective files. Execute docker compose down ; docker compose up -d to apply changes and restart the service.

โ“ 6. Common Issuesโ€‹

6.1 Text messages are sent normally, but sending pictures fails ๐Ÿ˜•โ€‹

This may be because the OPENIM_IP environment variable was not set before executing the docker compose up -d command. You can confirm this by checking the startup logs or by using the following command to search for "127.0.0.1" in the logs:

grep "127.0.0.1" openim-server/_output/logs/openim-docker.log

Solution:โ€‹

  1. Set the OPENIM_IP environment variable to your public IP address, or to your internal IP address if only providing internal network service:

    export OPENIM_IP="<Public-IP>"

  2. Use the sed command to update the apiURL and signEndpoint configuration items in the config.yaml file, changing the address to use the OPENIM_IP environment variable specified IP address:

    sed -i -e "s/apiURL: \"http:\/\/127\.0\.0\.1/apiURL: \"http:\/\/${OPENIM_IP}/" \
           -e "s/signEndpoint: \"http:\/\/127\.0\.0\.1/signEndpoint: \"http:\/\/${OPENIM_IP}/" \
           openim-server/config/config.yaml

After making these configuration changes and restarting the service, you should be able to send picture messages normally.

6.2 About Docker Versions ๐Ÿ‹โ€‹

It is strongly recommended to use the docker compose command instead of docker-compose, as older versions of Docker may not support the gateway featureโŒ. We advise upgrading to a newer version, such as 23.0.1๐Ÿ”.

6.3 Viewing Logs ๐Ÿ“œโ€‹

Log locations:

  • Runtime logs: {openim-server, openim-chat}/_output/logs/openim-all.*
  • Startup logs: {openim-server, openim-chat}/_output/logs/openim-docker.log