Skip to main content

🛠 Docker Deployment

1. Environment and Component Requirements​

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

2. Docker Deployment​

2.1 Clone the Repository and Initialize​

git clone openim-docker && cd openim-docker && make init

💡 Tips

If you didn't clone directly on your machine, but instead downloaded the openim-docker as a compressed package, run the command find ./ -name "*.sh" | xargs chmod +x to grant execution permissions to the scripts.

2.2 Setting OPENIM_IP​

🔔 It is mandatory to set OPENIM_IP, and it cannot be

# If the server has a public IP
export OPENIM_IP="Public IP"

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

2.3 Start Services 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 Modifying Configuration Items​

This project's configuration items are quite complex, primarily because some configurations involve multiple files such as .env, openim-chat/config/config.yaml, and openim-server/config/config.yaml. The modification instructions are divided into two parts: shared configuration items and other configuration items.

5.1 Shared Configuration Items​

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

  1. mysql/mongo/redis/kafka/zookeeper/minio ports and passwords;
  2. SECRET;

5.2 Modification Methods​

For modifying shared configuration items in section 5.1, choose one of the two methods below.

Method One: Regenerate All Configurations

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

  1. Delete existing configuration files: delete openim-server/config/config.yaml and openim-chat/config/config.yaml files.
  2. Modify .env file: update the related configuration items in the .env file.
  3. Regenerate configurations and restart services: execute docker compose down ; docker compose up -d. This will regenerate configuration files based on new settings in the .env file and restart the services.

Method Two: Modify Multiple Configuration Files Separately

If only partial updates are needed, follow these steps:

  1. Modify .env file: update the related configuration items in the .env file.

  2. Manually update configuration files: according to the changes in the .env file, correspondingly update the configuration items in openim-server/config/config.yaml and openim-chat/config/config.yaml.

  3. Special handling for specific variables: if OPENIM_IP, API_OPENIM_PORT, MINIO_PORT, GRAFANA_PORT are modified, update the following configuration items in openim-server/config/config.yaml:

    apiURL: "http://$OPENIM_IP:$API_OPENIM_PORT"
    endpoint: "http://$DOCKER_BRIDGE_GATEWAY:$MINIO_PORT"
    signEndpoint: "http://$OPENIM_IP:$MINIO_PORT"

    grafanaUrl: http://$OPENIM_IP:$GRAFANA_PORT
  4. Restart services: execute docker compose down ; docker compose up -d to apply changes and restart services.

5.3 Modifying Other Configuration Items​

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

❓ 6. Common Issues​

6.1 Can send text messages normally, but sending images fails 😕​

This issue might occur if 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 using the following command to search for the "" address in the logs:

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


  1. Set the OPENIM_IP environment variable to your public IP address, or to your internal IP address if you are providing services within a LAN:

    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}/" \

After modifying the configuration and restarting the service with the above steps, sending images should work normally.

6.3. Regarding Docker Version 🐋​

It is strongly recommended to use the docker compose command instead of docker-compose, as older Docker versions might not support the gateway feature❌. We advise upgrading to a newer version, such as 23.0.1🔝.

6.2 📜 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