Guides

Source Deployment

Build and run OpenIMServer and ChatServer from stable release tags.

This guide explains how to compile and run OpenIMServer and ChatServer from stable release source code in a single-host production environment. OpenIMServer and external backing dependencies are co-located on the same host, with select components optionally replaceable by cloud services.

Prepare environment and external components

First confirm the operating system, hardware, and software prerequisites in Environment and components.

Obtain OpenIMServer

Deploy using the latest official release tag marked with the green Latest badge on GitHub Releases. Never deploy the main branch or alpha, beta, rc, or other pre-release versions into production.

git clone https://github.com/openimsdk/open-im-server && cd open-im-server
git fetch --tags
LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)")
git checkout "$LATEST_STABLE_TAG"
echo "using open-im-server stable release tag: $LATEST_STABLE_TAG"

Execute all subsequent OpenIMServer commands from the repository root directory.

Deploy external components with Docker Compose

Ensure docker and docker compose are available, then complete the following configuration steps:

If MongoDB, Redis, Kafka, MinIO, or Etcd are already running locally, or if you plan to use managed cloud services, comment out the corresponding services in docker-compose.yml. Note that managed cloud services are not supported for Etcd.
Change the default usernames and passwords for all backing components.
Update DATA_DIR in .env to store external component data on a disk volume with adequate capacity.

Component	Configuration in `docker-compose.yml`
MongoDB	`MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD`, `MONGO_OPENIM_USERNAME`, `MONGO_OPENIM_PASSWORD`
Redis	`redis-server --requirepass ...`
MinIO	`MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`
Etcd	`ETCD_ROOT_USER`, `ETCD_ROOT_PASSWORD` when authentication is enabled
Kafka	`KAFKA_USERNAME`, `KAFKA_PASSWORD` when authentication is enabled

docker compose up -d

Currently, open-im-server/docker-compose.yml also starts openim-web-front and openim-admin-front in addition to the external dependencies. If you only require the backing services, adjust the Compose file before starting.

Initialization requirements for self-hosted components or cloud services

Storage component	Initialization requirement
MongoDB	Pre-create the `openim_v3` database
Kafka	Pre-create 4 topics: `toRedis`, `toMongo`, `toPush`, and `toOfflinePush`, each configured with 8 partitions

Build and start OpenIMServer

bootstrap.sh attempts to install Mage, but a functional Go environment must already be present on the host. Verify that go version succeeds before proceeding.

In mainland China network environments, configure a Go module proxy:

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct

Run initialization once:

bash bootstrap.sh

Compile:

mage

Update OpenIMServer basic configuration

Configuration	File
Kafka username, password, and endpoints	`config/kafka.yml`
Redis password and endpoints	`config/redis.yml`
MinIO credentials, internal endpoints, and external address	`config/minio.yml`
S3 cloud storage credentials	`config/openim-rpc-third.yml`
Etcd username, password, and endpoints	`config/discovery.yml`
MongoDB username, password, and endpoints	`config/mongodb.yml`
OpenIMServer `secret`	`config/share.yml`

The externalAddress setting in config/minio.yml must be a public IP or domain path accessible by client devices; otherwise, image and file messages cannot be retrieved.

Manage OpenIMServer services

Task	Command
Start in the background	`nohup mage start >> _output/logs/openim.log 2>&1 &`
Stop	`mage stop`
Check health	`mage check`

After the initial startup, wait 20-30s before running mage check or API verification so transient startup connection attempts are not mistaken for permanent errors.

Build and start ChatServer

If you already operate an existing user authentication system, ChatServer is optional. When ChatServer is needed, pin the official release tag matching your OpenIMServer version:

git clone https://github.com/openimsdk/chat && cd chat
git fetch --tags
LATEST_STABLE_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/chat/releases/latest)")
git checkout "$LATEST_STABLE_TAG"
echo "using chat stable release tag: $LATEST_STABLE_TAG"

Compile from the ChatServer repository root:

mage

Update ChatServer basic configuration

Configuration	File
Redis username, password, and endpoints	`config/redis.yml`
Etcd username, password, and endpoints	`config/discovery.yml`
MongoDB username, password, and endpoints	`config/mongodb.yml`
OpenIMServer `secret`	`config/share.yml`
ChatServer `secret`	`config/chat-rpc-admin.yml`

Manage ChatServer services

Task	Command
Start in the background	`nohup mage start >> _output/logs/chat.log 2>&1 &`
Stop	`mage stop`
Check health	`mage check`

ChatServer depends directly on OpenIMServer. Verify that OpenIMServer passes mage check first, then launch ChatServer and wait 20-30s before testing ports 10008 and 10009.

Configuration and optional capabilities

Comprehensive configuration guides for both repositories are maintained in config/README_zh_CN.md within the checked-out source code.
GeTui: Obtain AppID, AppKey, and MasterSecret before integrating.
Firebase: Configure fcm.filepath in config/openim-push.yml.
Monitoring and alerting: Refer to Monitoring and alerting.

Adjust service instance counts

Under serviceBinaries in start-config.yml, instance counts can be scaled directly for all services except openim-msggateway and openim-api. For openim-msggateway and openim-api, the instance count must strictly equal the number of listening ports defined in their respective configuration files. Restart services after modifying these values.

Pre-launch checklist

Update default secret tokens in OpenIMServer and ChatServer to alphanumeric combinations of at least 8 characters and store them securely.
If deploying without a domain name, configure firewalls and client connection addresses per Ports and network.
If deploying with a domain name, unify API, WebSocket, and object storage ingress per Domain configuration.
Prepare disaster recovery and verification workflows according to Production checks.
Complete process, API, and WebSocket validations as detailed in Deployment verification.