OpenIMSDKDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse OpenIMSDK Guides
GUIDESOpenIMSDK Guides

OpenIMSDK guides organized by implementation stage, from product concepts and deployment to integration, extension, operations, and reliability.

Guides

Air-Gapped Deployment

Export deployment artifacts on an online builder and run them offline.

Copy

The core workflow for air-gapped (offline) deployment is: run mage export on an internet-connected build host to generate deployment archives, then transfer those archives to the offline target host for execution.

Version and overall workflow

main is the active development branch containing unreleased continuous-integration changes. For air-gapped production environments, standardize on the latest official release designated by the green Latest badge on GitHub Releases, or a stable release tag explicitly verified by your team.

  1. Clone stable release source code for OpenIMServer and ChatServer on an internet-connected build host.
  2. Execute mage export to generate self-contained deployment archives suitable for air-gapped transfer.
  3. Transfer the deployment archives, runtime configurations, and external dependency installation packages to the offline target host.
  4. Extract the deployment archives on the target host and use the bundled ./mage binary to start and verify services.

Prepare external components

The exported archives for OpenIMServer and ChatServer contain only application services. You must prepare MongoDB, Redis, Kafka, Etcd, and MinIO separately.

Target host using Docker

On an internet-connected host, download Docker offline installation packages matching the target host's operating system and architecture:

  • Debian / Ubuntu: Prepare .deb packages for docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin.
  • RHEL / CentOS: Prepare the corresponding .rpm packages.

After installing Docker, use docker load to import pre-saved container images for the external backing components.

Target host not using Docker

Copy official binaries or internal prebuilt packages for MongoDB, Redis, Kafka, Etcd, and MinIO directly to the target host, managing them via systemd, supervisor, or custom process scripts. OpenIMServer and ChatServer only require network reachability and valid authentication credentials; Docker is not mandatory on the target host.

Export OpenIMServer on the build host

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"

bash bootstrap.sh
PLATFORMS="linux_amd64" mage export

Archives are generated in _output/export/ by default, named similarly to:

exported_open-im-server_v3.8.3-patch.12_linux_amd64.tar.gz

Export ChatServer on the build host

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"

bash bootstrap.sh
PLATFORMS="linux_amd64" mage export

The output file will be named similarly to:

exported_chat_v1.8.4-patch.3_linux_amd64.tar.gz

The archive produced by mage export includes compiled binaries, start-config.yml, runtime configuration files, and a prebuilt Mage runner that can be executed directly on the target host. The target host does not require a Go compiler or rebuild steps.

Transfer deployment materials

Copy the following assets to the offline target host:

  • OpenIMServer export archive
  • ChatServer export archive
  • External dependency container images or binary installation packages
  • Production configuration files, including domains, component endpoints, secret tokens, and the MinIO externalAddress

Deploy external components on the target host

When using Docker, import each image and start containers using your prepared Compose manifest:

docker load -i image-name.tar

When deploying without Docker, start MongoDB, Redis, Kafka, Etcd, and MinIO sequentially, and record their network endpoints, usernames, and passwords in the OpenIMServer and ChatServer configuration files.

Start OpenIMServer

mkdir -p /opt/openim/open-im-server
tar -xzf exported_open-im-server_v*.tar.gz -C /opt/openim/open-im-server
cd /opt/openim/open-im-server

Update external component endpoints, secret tokens, and MinIO externalAddress, then start the server:

./mage check
./mage start
./mage check

Start ChatServer

mkdir -p /opt/openim/chat
tar -xzf exported_chat_v*.tar.gz -C /opt/openim/chat
cd /opt/openim/chat

Update Redis, MongoDB, Etcd endpoints, and the OpenIMServer secret, then start the server:

./mage check
./mage start
./mage check

Common operational commands

OpenIMServer:

cd /opt/openim/open-im-server
./mage check
./mage stop
./mage start

ChatServer:

cd /opt/openim/chat
./mage check
./mage stop
./mage start

Operational caveats

  1. Never build air-gapped production packages from the main branch.
  2. Execute the bundled ./mage runner directly on the target host; do not re-run source compilation steps.
  3. If the build host and target host differ in CPU architecture, specify the target platform using PLATFORMS, such as linux_amd64 or linux_arm64.
  4. Regardless of whether external components are deployed via Docker or native binaries, verify that network addresses and credentials strictly match OpenIMServer and ChatServer configuration files.