OpenIM Docker

1. Environment Preparation
1. OpenIM Docker Usage Guide
- 2.1. Project Structure Explanation
- 2.2. Obtain the Image
1. Repository Setup
1. Basic Configuration
1. Advanced Configuration
1. Configuration Reading Priority
1. Starting the Service
1. Verification
1. Directory Structure
1. Deploying with example
1. Configuration File Modification
1. Common Configurations
1. OpenIM Docker Upgrade
1. Cleaning Up Deployment
1. Additional Information
1. Common Issues
- 16.1. Troubleshooting
1. Contribution
- 17.1. Conclusion
1. License

This guide provides detailed instructions for deploying OpenIM v3.5 using Docker Compose. It covers all steps from preparing the environment to verifying the deployment.

Warning

Note that this guide is only applicable to OpenIM v3.5. If you want to use older versions, please refer to other release-* branches.

Documentation

https://docs.openim.io/zh-Hans/guides/gettingStarted/dockerCompose

1. Environment Preparation

Ensure a clean server environment. For details, visit OpenIM Environment Setup.
Install Docker on the server.

2. OpenIM Docker Usage Guide

2.1. 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/.

2.2. Obtain the Image

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

GitHub Packages
Alibaba Cloud
Docker Hub

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

3. Repository Setup

Clone the repository and select the appropriate branch:

git clone -b refactor/openim-docker https://github.com/openimsdk/openim-docker openim-docker && cd openim-docker && make init

4. Basic Configuration

Use curl http://ifconfig.me to determine your external service IP.
Set your IP address in the environment:

export OPENIM_IP="Your IP Address"

If you forget this step, refer to [Configuration File Modification](#Configuration File Modification) later.

5. Advanced Configuration

For complex configurations:

Copy the .env file and perform necessary configurations using make init.
Refer to the OpenIM Server Environment Documentation for detailed guidance.

6. Configuration Reading Priority

The highest priority is values read from environment variables, followed by values in the .env file, and lastly, default values in the docker-compose.yaml file.

7. Starting the Service

Start the OpenIM service:

docker compose up -d

8. Verification

OpenIM Server: Check logs with docker compose logs -f openim-server.
OpenIM Chat: Validate logs with docker compose logs -f openim-chat.
OpenIM Web: Visit http://127.0.0.1:11001, register, and verify sending pictures and text between accounts.
OpenIM Management: Visit https://127.0.0.1:11002, use the default credentials admin1, admin1.

9. Directory Structure

smile@openim-docker$ tree 
.
├── 📝 `docker-compose.yaml` - *Docker Compose configuration file for defining and running multi-container Docker applications.*
├── 📂 `example` - *Contains various example configuration files and scripts showing how to configure and use OpenIM services.*
│   ├── 📄 `basic-openim-server-dependency.yml` - *Basic OpenIM server dependency configuration.*
│   ├── 📄 `full-openim-server-and-chat.yml` - *Complete configuration for OpenIM server and chat services.*
│   ├── 📄 `full-openim-server-chat-web-admin.yml` - *Comprehensive configuration including server, chat, web interface, and admin tools.*
│   ├── 📄 `only-openim-server.yml` - *Configuration for only the OpenIM server.*
│   └── 📄 `volume-all-server.yml` - *Volume configuration file for the server.*
├── 📄 `FAQ-CN.md` - *Frequently asked questions document in Chinese.*
├── 📄 `FAQ.md` - *Frequently asked questions document in English.*
├── 📄 `LICENSE` - *Project license file.*
├── 📄 `Makefile` - *Automated build tool configuration file.*
├── 📂 `openim-server` - *Related files for the OpenIM server.*
│   └── 📂 `_output`
│       └── 📂 `logs`
│           └── 📄 `openim_20240102.log` - *Server log file.*
├── 📄 `README.md` - *Project's English documentation.*
├── 📄 `README_zh-CN.md` - *Project's Chinese documentation.*
└── 📂 `scripts` - *Initialization, configuration, and upgrade scripts for the project.*
    ├── 📄 `clean.sh` - *Cleaning script.*
    ├── 📄 `create-topic.sh` - *Script for creating message topics.*
    ├── 📄 `init-config.sh` - *Initialization script for configuration.*
    ├── 📄 `mongo-init.sh` - *Script for initializing MongoDB.*
    ├── 📄 `README.md`

 - *Documentation for scripts.*
    ├── 📂 `template` - *Template files for the project.*
    │   ├── 📄 `boilerplate.txt`
    │   ├── 📄 `footer.md.tmpl`
    │   ├── 📄 `head.md.tmpl`
    │   ├── 📄 `LICENSE`
    │   ├── 📄 `LICENSE_TEMPLATES`
    │   └── 📄 `project_README.md`
    └── 📄 `upgrade.sh` - *Script for upgrading the project.*

docker-compose.yaml: A Docker Compose file for defining and running multi-container Docker applications. It describes the services, networks, and volumes required by the application.
example directory: Contains multiple example configuration files for showcasing the use and deployment of OpenIM services.
- basic-openim-server-dependency.yml: Basic configuration for OpenIM server dependencies.
- full-openim-server-and-chat.yml: Complete configuration including OpenIM server and chat services.
- full-openim-server-chat-web-admin.yml: Full set of configurations including server, chat, web interface, and admin tools.
- only-openim-server.yml: Configuration for only the OpenIM server.
- volume-all-server.yml: Used to configure volumes for the server, mounted to containers in Volume format.
FAQ-CN.md and FAQ.md: Frequently asked questions documents in Chinese and English, respectively, providing answers to common questions from OpenIM users.
Makefile: A build automation tool configuration file to simplify the compiling and installation process.
openim-server directory: Contains related files for the OpenIM server, all generated by mapping out from the openim-server service after startup.
- _output/logs: Stores log files, like openim_20240102.log recording logs for a specific date.
_output directory: Typically contains outputs from the build process, such as binary files, temporary files, and tools.
- bin: Compiled binary files.
- tmp: Temporary files.
- tools: Tools used by the project.
README.md and README_zh-CN.md: Project's documentation files in English and Chinese, providing an overview and basic information about the project.
scripts directory: Contains multiple script files for project initialization, configuration, and upgrade.
- clean.sh: Cleaning script for removing temporary files or build outputs.
- create-topic.sh and mongo-init.sh: Scripts for initializing databases and message queues.
- init-config.sh: Initialization script for configuration.
- README.md: Description of the scripts directory.
- template subdirectory: Contains project template files, like license templates and README templates.
- upgrade.sh: Script for upgrading the project.

10. Deploying with example

Note that if deploying using example, the DATA_DIR variable needs to be set to specify the location for data storage.

export DATA_DIR="/test/test"

DATA_DIR will store configuration information, data, and logs for middleware, as well as configuration information and logs for openim-server and openim-chat.

For example, when deploying openim-server, openim-chat, openim-admin, and openim-web, use:

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

To check the logs:

docker-compose -f example/full-openim-server-chat-web-admin.yml logs -f openim-server
docker-compose -f example/full-openim-server-chat-web-admin.yml logs -f openim-chat

To check the data storage location:

cat example/.env |grep DATA_DIR

To clear data:

docker-compose -f example/full-openim-server-chat-web-admin.yml down
rm -rf "Data Storage Location"

Directory Structure:

$ tree /test/ -L 3
/test/
└── test
    ├── components
    │   ├── kafka
    │   ├── mnt
    │   ├── mongodb
    │   ├── mysql
    │   └── redis
    └── openim-server
    │   ├── config
    │   ├── logs
    │   └── _output
    │
    └── openim-chat
        ├── config
        └── logs

11. Configuration File Modification

Before modifying the configuration file, use docker compose down to stop the service.

To modify the configuration, mainly focus on the .env file.
Use make init to initialize the configuration file.
In Docker, for shared variables in .env, openim-server/config/config.yaml, and openim-chat/config/config.yaml, follow steps for completely regenerating configuration or partial updates.
For specific updates such as OPENIM_IP, API_OPENIM_PORT, MINIO_PORT, etc., ensure they are updated in openim-server/config/config.yaml.

object:
  apiURL: "http://$OPENIM_IP:$API_OPENIM_PORT"
  minio:
    endpoint: "http://$DOCKER_BRIDGE_GATEWAY:$MINIO_PORT"
    signEndpoint: "http://$OPENIM_IP:$MINIO_PORT"

grafanaUrl: http://$OPENIM_IP:$GRAFANA_PORT

12. Common Configurations

Set OPENIM_IP, DATA_DIR, and IMAGE_REGISTRY according to your needs.
For database configurations like MySQL, Redis, Kafka, MongoDB, MinIO, and Zookeeper, update the respective ports and credentials.

13. OpenIM Docker Upgrade

Upgrading from V3.4 to V3.5 involves code changes and deployment structure reconfiguration, currently not supporting automatic upgrades.
For minor updates (and those after v3.5), which do not involve adding or removing configuration files, modify SERVER_IMAGE_VERSION and CHAT_IMAGE_VERSION in the .env file.
Use git pull and make upgrade to update the repository.

14. Cleaning Up Deployment

Use docker compose down to stop the service.
Use sudo make clean to clean up configurations.
Optionally clean data and prune unused networks: docker network prune -f

15. Additional Information

Ensure the IP and port environment variables for chat are consistent.
For quick verification, management backend, monitoring system, and more detailed configuration instructions, refer to the OpenIM documentation.

16. Common Issues

The new version of Docker integrates docker-compose. Older versions may not support the gateway feature. It's recommended to upgrade to a newer version, such as 23.0.1.
For deployment issues, search or raise an issue at https://github.com/openimsdk/openim-docker/issues. If the issue doesn't exist, please help us by raising it.

16.1. 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

17. 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.

17.1. 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.

18. License

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

sskyy / openim-docker