Docker Compose Deployment

Prepare the environment

Before proceeding, review Environment and components for server hardware, software, operating system, and external dependency requirements.

Deploy OpenIMServer

Clone the repository and pin a stable release

Always use the latest official release tag marked with the green Latest badge on GitHub Releases. Avoid relying on alphanumeric tag sorting, and do not deploy alpha, beta, rc, or other pre-release versions into production.

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"

main is the active development branch. Never deploy main directly to production.

Configure public object storage address

Edit .env to set the external MinIO access address reachable by client devices:

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

Start and stop services

Start all services:

docker compose up -d

The initial run downloads relatively large container images. After containers start, wait 30-60s before executing health checks or API verification.

This guide assumes a clean machine environment. If containers named mongo, redis, kafka, etcd, minio, openim-server, or openim-chat already exist on the host, docker compose up -d will fail due to container_name conflicts. Remove or rename conflicting containers first, or reuse existing components and adjust configuration accordingly.

If startup logs warn that ETCD_USERNAME, ETCD_PASSWORD, KAFKA_USERNAME, or KAFKA_PASSWORD are unset, and you have not enabled authentication on those components, you can safely ignore these notices.

Stop all services:

docker compose down

Tail logs for OpenIMServer and ChatServer:

docker compose logs -f openim-server openim-chat

Start monitoring and alerting (optional)

To launch Prometheus, Alertmanager, Grafana, and node-exporter alongside the core services, run:

docker compose --profile m up -d

Default listening ports are governed by .env. Typical port allocations:

Verify deployment

After startup completes, follow Deployment verification to validate OpenIMServer, ChatServer, REST APIs, WebSocket connectivity, and optional frontends.

Troubleshooting

Containers remain unhealthy

1. Run docker exec -it openim-server mage check and docker exec -it openim-chat mage check to verify if failures persist for more than one minute.
2. Run docker compose logs -f openim-server openim-chat to inspect detailed container logs.
3. If openim-chat briefly logs connect: connection refused during initial startup, wait 30-60s and recheck. This is normal startup sequencing behavior while openim-server completes initialization.

Configuration modifications do not take effect

Modifying files inside the container's config directory directly does not persist across container recreations. Configure parameters via environment variables instead; refer to the openim-docker environment variable documentation.