/openim-docker

openim-docker configuration for deploying OpenIM. Provides a build solution for a stable distribution, as well as a docker compose deployment strategy

Primary LanguageShellMIT LicenseMIT

OpenIM Docker Deployment

OpenIM Docker offers a stable solution for building and deploying OpenIM. There are many deployment options available, and the process is simplified using Docker and Docker Compose.

English • 简体中文

Directory Structure

OpenIM Docker Deployment
│
├── 📁 **build/**
│   ├── 📄 Dockerfile-server
│   └── 📄 Dockerfile-chat
│
├── 📁 **openim-server/**
│   ├── 📁 release-v*.*/
│   └── 📁 main/
│
├── 📁 **openim-chat/**
│   ├── 📁 release-v*.*/
│   └── 📁 main/
│
├── 📁 **env/**
│   ├── 📄 openim-server.env
│   └── 📄 openim-chat.env
│
└── 📁 **example/**
    ├── 📄 basic-openim-server-dependency.yml
    ├── 📄 only-openim-server.yml
    └── 📄 full-openim-server-and-chat.yml
  • build/: For building Docker images.
  • openim-server/: For deploying openim-server.
  • openim-chat/: For deploying openim-chat.
  • env/: Contains environment variable files for Docker-compose. (Not needed for now)
  • example/: Contains various Docker-compose examples, offering feature deployment schemes.

Project Structure Explanation

  • For changes to openim-server and openim-chat, please contribute separately at https://github.com/OpenIMSDK/Open-IM-Server/ and https://github.com/OpenIMSDK/chat.
  • To synchronize scripts and configuration files of the two projects, we use automation tools. Just ensure that the files are synchronized with the original repository.
  • For environment variable files and Docker-compose examples, make changes under env/ and example/.

OpenIM Docker Usage Guide

1. Obtain the Image

You can get the Docker image from the following three sources:

To ensure you get the latest version of the image, please refer to the following documents:

2. Using Docker-compose

Setting Environment Variables

You can set environment variables or use the default ones based on your needs. Configuration options can be found at https://github.com/OpenIMSDK/Open-IM-Server/blob/main/scripts/install/environment.sh

export PASSWORD="openIM123" # Set password, default is openIM123
export USER="root" # Set username, default is root
# Choose chat version and server version https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/images.md, eg: main, release-v*.*
export CHAT_BRANCH="main"   # Set chat version, default is release-v3.3 (unstable)
export SERVER_BRANCH="main" # Set server version, default is release-v3.3 (unstable)
# ...... other environment variables
# MONGO_USERNAME: Set MongoDB username
# MONGO_PASSWORD: Set MongoDB password
# MONGO_DATABASE: Set MongoDB database name
# MINIO_ENDPOINT: Set MinIO service address
# API_URL: In a local network environment, set OpenIM Server API address
export API_URL="http://127.0.0.1:10002"
# DOCKER_BRIDGE_SUBNET: Set Docker bridge network address, default is 172.28.0.0/16
export DOCKER_BRIDGE_SUBNET=172.28.0.0/16

These are just a few common configuration options. If you don't need them, you can read through our config center instructions.

Render the required configuration via './scripts/init-config.sh 'or' make init '. It can be modified directly https://github.com/openimsdk/openim-docker/blob/main/scripts/install/environment.sh or set linux environment variables. For example, above PASSWORD and USER. The latter method works only on the current terminal

One-click Deployment:

git clone https://github.com/openim-sigs/openim-docker openim/openim-docker && export openim=$(pwd)/openim && cd $openim/openim-docker && ./scripts/init-config.sh && docker compose up -d

Troubleshooting:

Common issues are documented in FAQ.md. If you encounter any issues, you can refer to this document.

It's also possible to find issues that have been encountered before, if not, please provide us with an issue description

Modify Configuration Files:

There are three ways to modify the configuration files:

1. Recommended: Use environment variables (as mentioned above).

For updating configurations:

make init
2. Modify the automation script:
scripts/install/environment.sh

To update the configuration:

make init
3. Modify the config.yaml and .env files (but note that reusing make init to generate configurations will overwrite them).

Default Startup Selection:

docker-compose up -d

Note: If image fetching is slow, you can choose the image from Alibaba Cloud. For both openim-server and openim-chat, they are interchangeable. You only need to modify the image in the docker-compose.yml file.

# image: ghcr.io/openimsdk/openim-server:latest
image: registry.cn-hangzhou.aliyuncs.com/openimsdk/openim-server:latest
# image: openim/openim-server:latest

OpenIM Data Storage Architecture Guide

II. OpenIM Default Data Storage Structure

A. Overview

At the heart of OpenIM's data storage are the essential components: Kafka, MNT, MongoDB, MySQL, and Redis. Each serves a distinct purpose and requires specific configuration and data directories for optimal performance.

B. Directory Structure

$ tree components/ -d -L 2
components/
├── kafka
│   ├── config
│   └── data
├── mnt
│   ├── config
│   └── data
├── mongodb
│   └── data
├── mysql
│   └── data
└── redis
    ├── config
    └── data

III. Customizing OpenIM's Data Storage

A. Setting a Custom Directory

For organizations with specific storage directory requirements, OpenIM offers the flexibility to specify a custom directory. Follow these steps:

  1. Define your custom directory path by setting the DATA_DIR environment variable:
$ export DATA_DIR="/path/to/your/directory"
  1. Refresh OpenIM's configuration to reflect this change:
$ make init

Note: This action will update the configuration to point to the directory you've specified.

IV. Docker Volume Storage: An Advanced Approach

A. Why Docker Volumes?

Docker volumes offer isolated storage solutions, optimizing data persistence and performance. When scaling services in Docker, using volumes ensures that data remains consistent and protected.

B. Using Docker Volumes with OpenIM

To launch OpenIM with Docker volume support, execute:

$ docker compose -f example/volume-all-server.yml up -d

With this setup, your OpenIM data is securely mounted onto Docker's volumes, providing added resilience and scalability.

C. Managing Docker Volumes

  1. Listing OpenIM Docker Volumes

Retrieve a list of Docker volumes associated with OpenIM using:

$ docker volume ls | grep open-im-server
  1. Removing Data
  • For locally mapped data: Simply navigate to the appropriate directory and delete the desired files or folders.
  • For Docker volume data: If you wish to clear data from Docker volumes, employ the command below:
$ docker volume ls | grep open-im-server | awk '{print $2}' | xargs docker volume rm

Warning: This action will permanently erase the data. Always ensure you have backups before proceeding.

Custom Startup

Based on your requirements, choose the appropriate Docker-compose file to start:

  • Basic Environment Dependency:

    docker-compose -f example/basic-openim-server-dependency.yml up -d

  • Only OpenIM Server:

    docker-compose -f example/only-openim-server.yml up -d

  • Both OpenIM Server and Chat:

    docker-compose -f example/full-openim-server-and-chat.yml up -d

Mounting:

In the Docker Compose file, the "volumes" keyword defines named volumes. Named volumes are a storage concept in Docker that allows you to create persistent storage for a container. This means that even if the container is deleted, the data stored on that volume will not be lost.

For easy management, we use named volumes. These volumes have the same name as the services. For instance, the openim-server service uses the openim-server named volume, and the openim-chat service uses the openim-chat named volume.

View all volumes:

docker volume ls

View a specific volume:

docker volume inspect <volume-name>

Delete a named volume:

docker volume rm <volume-name>

Delete unused volumes:

docker volume prune

Customizing Your Image

For easy customization, we provide basic images of various distributions and architectures. The repository address is https://github.com/OpenIMSDK/openim-base-image, for easy customization.

Test Running Status

To see if all services have started, you can use:

docker-compose ps

If you find a container that hasn't started, you can view the logs of the specific service to find out the reason. For example, to view the logs of OpenIM Server:

docker-compose logs openim-server

Stop

To stop all services running by Docker-compose:

docker-compose down

If you used a specific docker-compose file, make sure to specify it in the down command as well.

3. Tips

Ensure your Docker and Docker Compose are up-to-date to guarantee the best compatibility and performance.

Contribution

  • Fork this repository to your GitHub account.
  • Clone the forked repository to your local environment.
  • Create a new branch and name it after your contribution.
  • Make changes where needed.
  • Commit your changes and push them to your fork.
  • Create a new Pull Request on GitHub.

We encourage community contributions and improvements to this project. For the specific contribution process, please refer to CONTRIBUTING.md.

Conclusion

OpenIM's flexible storage solutions empower organizations to configure their infrastructure in alignment with their specific needs. Whether through default directories, custom paths, or Docker volumes, OpenIM guarantees efficient and secure data management.

For further assistance or advanced configurations, please consult our technical support team or refer to OpenIM's comprehensive documentation.

License

This project uses the MIT license. For details, please refer to LICENSE.