open-im-server/docs/contrib/mac-developer-deployment-guide.md

Mac Developer Deployment Guide for OpenIM

Introduction

This guide aims to assist Mac-based developers in contributing effectively to OpenIM. It covers the setup of a development environment tailored for Mac, including the use of GitHub for development workflow and devcontainer for a consistent development experience.

Before contributing to OpenIM through issues and pull requests, make sure you are familiar with GitHub and the pull request workflow.

Prerequisites

System Requirements

• macOS (latest stable version recommended)
• Internet connection
• Administrator access

Knowledge Requirements

• Basic understanding of Git and GitHub
• Familiarity with Docker and containerization
• Experience with Go programming language

Setting up the Development Environment

Installing Homebrew

Homebrew is an essential package manager for macOS. Install it using:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Installing and Configuring Git

1. Install Git:

   brew install git
   

2. Configure Git with your user details:

   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"
   

HEAD

Forking and Cloning the Repository

To optimize and add logic to your instructions, particularly regarding deploying on a Mac, you can modify them as follows:

1. Fork the OpenIM Repository: Fork the OpenIM repository on GitHub to your account.

2. Clone Your Fork to Your Local Machine: Open your terminal and execute the following commands:

   git clone https://github.com/<your-username>/open-im-server.git
   
   # Set Docker bridging network mode for Mac
   export DOCKER_BRIDGE_SUBNET=127.0.0.0/16
   export OPENIM_IP=<your-ip>
   make init
   docker compose up -d
   make start
   git clone https://github.com/<your-username>/open-im-server.git
   
   # Set Docker bridging network mode for Mac
   export DOCKER_BRIDGE_SUBNET=127.0.0.0/16
   
   # Set OpenIM IP
   export OPENIM_IP=<your-ip>
   
   # Initialize configuration
   make init
   
   # Start components using Docker
   docker compose up -d
   
   # Start OpenIM Server
   make start
   

3. Additional Steps for Mac Deployment: If you are deploying on a Mac and wish to use the chat feature, you need to modify the docker-compose file. Specifically, you'll need to uncomment the sections related to openim-chat and mysql.

   Here's how to do it:

   • Open the docker-compose.yml file in a text editor.
   • Find the sections for openim-chat and mysql.
   • Remove the comment marks (#) at the beginning of the lines in these sections to enable them.
   • Save the file after making these changes.

4. Update and Restart Services: After modifying the docker-compose file, you need to update and restart the services to apply these changes. Run the following command in your terminal:

   # Update and restart services
   docker compose up -d
   
   # Check openim-chat start
   docker compose logs openim-chat
   

   This command will re-read the docker-compose.yml file, apply the new configuration, and restart the necessary containers.

Remember, replacing <your-username> and <your-ip> with your actual GitHub username and desired IP address for OpenIM is crucial. These steps should streamline the setup process, particularly for Mac users wishing to use the chat feature.

origin/main

Setting Up the Devcontainer

Devcontainers provide a Docker-based isolated development environment.

Read README.md in the .devcontainer directory of the project to learn more about the devcontainer.

To set it up:

1. Install Docker Desktop for Mac from Docker Hub.
2. Install Visual Studio Code and the Remote - Containers extension.
3. Open the cloned OpenIM repository in VS Code.
4. VS Code will prompt to reopen the project in a container. Accept this to set up the environment automatically.

Installing Go and Dependencies

Use Homebrew to install Go:

brew install go

Ensure the version of Go is compatible with the version required by OpenIM (refer to the main documentation for version requirements).

Additional Tools

Install other required tools like Docker, Vagrant, and necessary GNU utils as described in the main documentation.

Mac Deployment openim-chat and openim-server

To integrate the Chinese document into an English document for Linux deployment, we will first translate the content and then adapt it to suit the Linux environment. Here's how the translated and adapted content might look:

Ensure a Clean Environment

• It's recommended to execute in a new directory.
• Run ps -ef | grep openim to ensure no OpenIM processes are running.
• Run ps -ef | grep chat to check for absence of chat-related processes.
• Execute docker ps to verify there are no related containers running.

Source Code Deployment

Deploying openim-server

Source code deployment is slightly more complex because Docker's networking on Linux differs from Mac.

git clone https://github.com/openimsdk/open-im-server
cd open-im-server

export OPENIM_IP="Your IP" # If it's a cloud server, setting might not be needed
make init # Generates configuration files

Before deploying openim-server, modify the Kafka logic in the docker-compose.yml file. Replace:

- KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092,EXTERNAL://${DOCKER_BRIDGE_GATEWAY:-172.28.0.1}:${KAFKA_PORT:-19094}

With:

- KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092,EXTERNAL://127.0.0.1:${KAFKA_PORT:-19094}

Then start the service:

docker compose up -d

Before starting the openim-server source, set config/config.yaml by replacing all instances of 172.28.0.1 with 127.0.0.1:

vim config/config.yaml -c "%s/172\.28\.0\.1/127.0.0.1/g" -c "wq"

Then start openim-server:

make start

To check the startup:

make check

🚧 To avoid mishaps, it's best to wait five minutes before running `make check` again.

Deploying openim-chat

There are several ways to deploy openim-chat, either by source code or using Docker.

Navigate back to the parent directory:

cd ..

First, let's look at deploying chat from source:

git clone https://github.com/openimsdk/chat
cd chat
make init # Generates configuration files

If openim-chat has not deployed MySQL, you will need to deploy it. Note that the official Docker Hub for MySQL does not support architectures like ARM, so you can use the newer version of the open-source edition:

docker run -d \
  --name mysql \
  -p 13306:3306 \
  -p 3306:33060 \
  -v "$(pwd)/components/mysql/data:/var/lib/mysql" \
  -v "/etc/localtime:/etc/localtime" \
  -e MYSQL_ROOT_PASSWORD="openIM123" \
  --restart always \
  mariadb:10.6

Before starting the source code of openim-chat, set config/config.yaml by replacing all instances of 172.28.0.1 with 127.0.0.1:

vim config/config.yaml -c "%s/172\.28\.0\.1/127.0.0.1/g" -c "wq"

Then start openim-chat from source:

make start

To check, ensure the following four processes start successfully:

➜  chat git:(main) ✗ ps -ef | grep chat      
# [Output showing four running chat processes]

Access the web interface: http://ip:11001

Docker Deployment

Refer to https://github.com/openimsdk/openim-docker for Docker deployment instructions, which can be followed similarly on Linux.

git clone https://github.com/openimsdk/openim-docker
cd openim-docker
export OPENIM_IP="Your IP"
make init
docker compose up -d 
docker compose logs -f openim-server
docker compose logs -f openim-chat

GitHub Development Workflow

Creating a New Branch

For new features or fixes, create a new branch:

git checkout -b feat/your-feature-name

Making Changes and Committing

1. Make your changes in the code.

2. Stage your changes:

   git add .
   

3. Commit with a meaningful message:

   git commit -m "Add a brief description of your changes"
   

Pushing Changes and Creating Pull Requests

1. Push your branch to GitHub:

   git push origin feat/your-feature-name
   

2. Go to your fork on GitHub and create a pull request to the main OpenIM repository.

Keeping Your Fork Updated

Regularly sync your fork with the main repository:

git fetch upstream
git checkout main
git rebase upstream/main

More read: https://github.com/openimsdk/open-im-server/blob/main/CONTRIBUTING.md

Testing and Quality Assurance

Run tests as described in the OpenIM documentation to ensure your changes do not break existing functionality.

Conclusion

This guide provides a comprehensive overview for Mac developers to set up and contribute to OpenIM. By following these steps, you can ensure a smooth and efficient development experience. Happy coding!