Skip to main content

Air-Gapped Deployment

📌 Air-Gapped Deployment Guide​

The main air-gapped deployment workflow is: run mage export on an internet-connected build machine, then transfer the deployment package to the internal target machine and run it there.

1. Version and Branch Strategy​

  • main: development branch, used only for unreleased changes.
  • vX.Y.Z...: stable release versions.
  • For air-gapped production, use the latest official release marked with the green Latest badge on GitHub Releases.

2. Overall Workflow​

  1. On an internet-connected build machine, pull the stable OpenIMServer / ChatServer source code.
  2. Run mage export on the build machine to generate deployable archives.
  3. Transfer the archives, configuration files, and external component installation packages to the internal target machine.
  4. Extract the archives on the internal target machine and directly use the bundled ./mage launcher to start and check services.

3. Ways to Prepare External Components​

The OpenIMServer / ChatServer air-gapped deployment package only contains the business services themselves. External components (MongoDB, Redis, Kafka, Etcd, MinIO) can be prepared in two ways.

Option A: The Target Machine Uses Docker​

If Docker is not installed on the target machine, it is recommended to download Docker offline installation packages matching the target OS and architecture on an internet-connected machine first, and then transfer them to the internal target machine.

  • 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 for the same components

After installation, use docker load to import the external component images you exported in advance.

Option B: The Target Machine Does Not Use Docker​

You can directly copy the official binaries or internal artifact packages of MongoDB, Redis, Kafka, Etcd, and MinIO to the internal target machine, and run them with their own systemd / supervisor / script-based startup methods.

In this mode, OpenIMServer / ChatServer only need correct addresses and credentials for these components. Docker is not required on the target machine.

4. Export OpenIMServer on the Internet-Connected Build Machine​

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

After a successful run, the deployment archive is generated by default in:

_output/export/

A typical filename looks like:

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

5. Export ChatServer on the Internet-Connected Build Machine​

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

A typical filename looks like:

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

6. Deployment Package Contents​

The archive generated by mage export includes:

  • prebuilt service binaries
  • start-config.yml
  • required runtime configuration files
  • a mage launcher that can be executed directly on the target machine

Therefore, the internal target machine does not need to install Go and does not need to rebuild source code.

7. Transfer to the Internal Target Machine​

Transfer the following to the internal target machine:

  • the OpenIMServer export archive
  • the ChatServer export archive
  • external component images or binary installation packages
  • your real configuration files, such as domain settings, external component addresses, secret, and MinIO externalAddress

8. Deploy External Components on the Internal Target Machine​

1. Docker Method​

If the target machine uses Docker:

docker load -i image-name.tar

After importing all external component images, start them with your component orchestration files.

2. Non-Docker Method​

If the target machine does not use Docker:

  • start MongoDB
  • start Redis
  • start Kafka
  • start Etcd
  • start MinIO

Then write the addresses, usernames, and passwords of these components into the OpenIMServer / ChatServer configuration files.

9. Extract and Start OpenIMServer on the Internal Target Machine​

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

After updating external component addresses, secret, and MinIO externalAddress, run:

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

10. Extract and Start ChatServer on the Internal Target Machine​

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

After updating Redis, MongoDB, Etcd, and the OpenIMServer secret in the ChatServer configuration, run:

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

11. Common Runtime 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

12. Notes for Air-Gapped Deployment​

  1. main is the development branch and should not be used for air-gapped production packages.
  2. The runtime dependencies for the target machine are already bundled in the mage export archive, so do not rerun the source build workflow on the target machine.
  3. If the target machine architecture differs from the build machine, specify the target platform with PLATFORMS, for example PLATFORMS="linux_amd64" mage export or PLATFORMS="linux_arm64" mage export.
  4. Whether you use Docker or direct binary deployment for external components, make sure the addresses and credentials match the OpenIMServer / ChatServer configuration.