-
- 16.1. Troubleshooting
-
- 17.1. Conclusion
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
- Ensure a clean server environment. For details, visit OpenIM Environment Setup.
- Install Docker on the server.
- 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/
.
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:
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
- 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.
For complex configurations:
- Copy the
.env
file and perform necessary configurations usingmake init
. - Refer to the OpenIM Server Environment Documentation for detailed guidance.
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.
- Start the OpenIM service:
docker compose up -d
- 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
.
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
andFAQ.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, likeopenim_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
andREADME_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
andmongo-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.
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
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
, andopenim-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 inopenim-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
- Set
OPENIM_IP
,DATA_DIR
, andIMAGE_REGISTRY
according to your needs. - For database configurations like MySQL, Redis, Kafka, MongoDB, MinIO, and Zookeeper, update the respective ports and credentials.
- 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
andCHAT_IMAGE_VERSION
in the.env
file. - Use
git pull
andmake upgrade
to update the repository.
- 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
- 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.
-
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.
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
- 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.
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.
This project uses the MIT license. For details, please refer to LICENSE.