Skip to main content

Docker Deployment

1. Environment Preparation 🌍​

For server hardware, software, operating system, and dependent components, please refer to this document.

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.

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"

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 .env and configure the MinIO external IP to support image and file sending. Replace your-server-ip with your server's public IP.

    MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005"

2.3 Start Services 🚀​

  • Start services:
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:
docker compose down
  • View logs:
docker compose logs -f openim-server openim-chat

2.4 Monitoring & Alerting (Optional)​

If you also want to start Prometheus, Alertmanager, Grafana, and node-exporter, run:

docker compose --profile m up -d

Here, m is the monitoring profile defined by openim-docker in docker-compose.yaml. Enabling it starts these extra services:

  • Prometheus: metrics collection
  • Alertmanager: alert routing
  • Grafana: monitoring dashboards
  • node-exporter: host metrics collection

Default ports follow the current .env. Common values are:

  • 19090: Prometheus
  • 19093: Alertmanager
  • 13000: Grafana
  • 19100: node-exporter

For production environments, it is recommended to enable monitoring and alerting, which means starting the m profile with docker compose --profile m up -d. openim-docker already includes Prometheus scrape configuration, Alertmanager configuration, and basic alert rules for cases such as instance failures, database exceptions, low registrations, and low message volume.

To actually receive alert notifications, complete the Alertmanager notification configuration for your environment, such as SMTP settings.

3. Quick Experience ⚡​

To quickly experience core OpenIMSDK capabilities and verify whether OpenIMServer / ChatServer deployment is working, refer to Quick Verification.

4. FAQ​

Troubleshooting unhealthy​

  1. Run docker exec -it openim-server mage check and docker exec -it openim-chat mage check, then confirm whether either state lasts longer than one minute.
  2. Run docker compose logs -f openim-server openim-chat 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.

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.