open-im-server Documentation

1. Project Overview & Quickstart (openimsdk/open-im-server) Copy Chapter

File: README.md Copy Chapter

:busts_in_silhouette: Join Our Community Copy Chapter

• 💬 Follow us on Twitter
• 🚀 Join our Slack
• :eyes: Join our WeChat Group

Ⓜ️ About OpenIM Copy Chapter

Unlike standalone chat applications such as Telegram, Signal, and Rocket.Chat, OpenIM offers an open-source instant messaging solution designed specifically for developers rather than as a directly installable standalone chat app. Comprising OpenIM SDK and OpenIM Server, it provides developers with a complete set of tools and services to integrate instant messaging functions into their applications, including message sending and receiving, user management, and group management. Overall, OpenIM aims to provide developers with the necessary tools and framework to implement efficient instant messaging solutions in their applications.

🚀 Introduction to OpenIMSDK Copy Chapter

OpenIMSDK, designed for OpenIMServer, is an IM SDK created specifically for integration into client applications. It supports various functionalities and modules:

• 🌟 Main Features:

  • 📦 Local Storage
  • 🔔 Listener Callbacks
  • 🛡️ API Wrapping
  • 🌐 Connection Management

• 📚 Main Modules:

  1. 🚀 Initialization and Login
  2. 👤 User Management
  3. 👫 Friends Management
  4. 🤖 Group Functions
  5. 💬 Session Handling

Built with Golang and supports cross-platform deployment to ensure a consistent integration experience across all platforms.

👉 Explore the GO SDK

🌐 Introduction to OpenIMServer Copy Chapter

• OpenIMServer features include:
  • 🌐 Microservices Architecture: Supports cluster mode, including a gateway and multiple rpc services.
  • 🚀 Diverse Deployment Options: Supports source code, Kubernetes, or Docker deployment.
  • Massive User Support: Supports large-scale groups with hundreds of thousands, millions of users, and billions of messages.

Enhanced Business Functions: Copy Section

• REST API: Provides a REST API for business systems to enhance functionality, such as group creation and message pushing through backend interfaces.

• Webhooks: Expands business forms through callbacks, sending requests to business servers before or after certain events.

:rocket: Quick Start Copy Chapter

Experience online for iOS/Android/H5/PC/Web:

👉 OpenIM Online Demo

To facilitate user experience, we offer various deployment solutions. You can choose your preferred deployment method from the list below:

• Source Code Deployment Guide
• Docker Deployment Guide

System Support Copy Chapter

Supports Linux, Windows, Mac systems, and ARM and AMD CPU architectures.

:link: Links Copy Chapter

• Developer Manual
• Changelog

:writing_hand: How to Contribute Copy Chapter

We welcome contributions of any kind! Please make sure to read our Contributor Documentation before submitting a Pull Request.

• Report a Bug
• Suggest a Feature
• Submit a Pull Request

Thank you for contributing to building a powerful instant messaging solution!

:closed_book: License Copy Chapter

This software is licensed under the Apache License 2.0

🔮 Thanks to our contributors! Copy Chapter

File: assets/demo/README.md Copy Chapter

:star2: Why OpenIM Copy Chapter

🔍 Function screenshot display

File: assets/README.md Copy Chapter

`/assets`

The /assets directory in the OpenIM repository contains various assets such as images, logos, and animated GIFs. These assets serve different purposes and contribute to the functionality and aesthetics of the OpenIM project.

Directory Structure: Copy Chapter

assets/
├── README.md                     # Documentation for the assets directory
├── images                        # Directory holding images related to OpenIM
│   ├── architecture.png          # Image depicting the architecture of OpenIM
│   └── mvc.png                   # Image illustrating the Model-View-Controller (MVC) pattern
├── intive-slack.png              # Image displaying the Intive Slack logo
├── logo                          # Directory containing various logo variations for OpenIM
│   ├── openim-logo-black.png     # OpenIM logo with a black background
│   ├── openim-logo-blue.png      # OpenIM logo with a blue background
│   ├── openim-logo-green.png     # OpenIM logo with a green background
│   ├── openim-logo-purple.png    # OpenIM logo with a purple background
│   ├── openim-logo-white.png     # OpenIM logo with a white background
│   ├── openim-logo-yellow.png    # OpenIM logo with a yellow background
│   └── openim-logo.png           # OpenIM logo with a transparent background
└── logo-gif                      # Directory containing animated GIF versions of the OpenIM logo
    └── openim-log.gif            # Animated OpenIM logo with a transparent background

Copyright Notice: Copy Chapter

The OpenIM logo, including its variations and animated versions, displayed in this repository OpenIM under the /assets/logo and /assets/logo-gif directories, are protected by copyright laws.

The logo design is credited to @Xx(席欣).

Please respect the intellectual property rights and refrain from unauthorized use and distribution of these assets.

File: config/README.md Copy Chapter

OpenIM Configuration File Descriptions and Common Configuration Modifications

External Component Configurations Copy Chapter

OpenIMServer Related Configurations Copy Chapter

Monitoring and Alerting Related Configurations Copy Chapter

Common Configuration Modifications Copy Chapter

Starting Multiple Instances of a Service and Maximum File Descriptors Copy Chapter

To start multiple instances of an OpenIM service, simply add the corresponding port numbers and modify the start-config.yml file in the project’s root directory,
then restart the service. For example, to start 2 instances of openim-rpc-user:

rpc:
  registerIP: ''
  listenIP: 0.0.0.0
  ports: [ 10110, 10111 ]

prometheus:
  enable: true
  ports: [ 20100, 20101 ]

Modifystart-config.yml:

serviceBinaries:
  openim-rpc-user: 2

To set the maximum number of open file descriptors (typically one per online user):

maxFileDescriptors: 10000

File: config/README_zh_CN.md Copy Chapter

OpenIM配置文件说明以及常用配置修改说明

外部组件相关配置 Copy Chapter

OpenIMServer相关配置 Copy Chapter

监控告警相关配置 Copy Chapter

常用配置修改 Copy Chapter

启动某个服务的多个实例和最大文件句柄数 Copy Chapter

若要启动某个OpenIM的多个实例，只需增加对应的端口数，并修改项目根目录下的start-config.yml文件，重启服务即可生效。例如，启动2个openim-rpc-user实例的配置如下：

rpc:
  registerIP: ''
  listenIP: 0.0.0.0
  ports: [ 10110, 10111 ]

prometheus:
  enable: true
  ports: [ 20100, 20101 ]

修改start-config.yml:

serviceBinaries:
  openim-rpc-user: 2

修改最大同时打开的文件句柄数，一般是每个在线用户占用一个

maxFileDescriptors: 10000

File: deployments/Readme.md Copy Chapter

Kubernetes Deployment

Resource Requests Copy Chapter

• CPU: 2 cores
• Memory: 4 GiB
• Disk usage: 20 GiB (on Node)

Preconditions Copy Chapter

ensure that you have already deployed the following components:

• Redis
• MongoDB
• Kafka
• MinIO

Origin Deploy Copy Chapter

Enter the target dir Copy Section

cd ./deployments/deploy/

Deploy configs and dependencies Copy Section

Upate your configMap openim-config.yml. You can check the official docs for more details.

In openim-config.yml, you need modify the following configurations:

discovery.yml

• kubernetes.namespace: default is default, you can change it to your namespace.

mongodb.yml

• address: set to your already mongodb address or mongo Service name and port in your deployed.
• database: set to your mongodb database name.(Need have a created database.)
• authSource: set to your mongodb authSource. (authSource is specify the database name associated with the user's credentials, user need create in this database.)

kafka.yml

• address: set to your already kafka address or kafka Service name and port in your deployed.

redis.yml

• address: set to your already redis address or redis Service name and port in your deployed.

minio.yml

• internalAddress: set to your minio Service name and port in your deployed.
• externalAddress: set to your already expose minio external address.

Set the secret Copy Section

A Secret is an object that contains a small amount of sensitive data. Such as password and secret. Secret is similar to ConfigMaps.

Redis:

Update the redis-password value in redis-secret.yml to your Redis password encoded in base64.

apiVersion: v1
kind: Secret
metadata:
  name: openim-redis-secret
type: Opaque
data:
  redis-password: b3BlbklNMTIz # update to your redis password encoded in base64, if need empty, you can set to ""

Mongo:

Update the mongo_openim_username, mongo_openim_password value in mongo-secret.yml to your Mongo username and password encoded in base64.

apiVersion: v1
kind: Secret
metadata:
  name: openim-mongo-secret
type: Opaque
data:
  mongo_openim_username: b3BlbklN # update to your mongo username encoded in base64, if need empty, you can set to "" (this user credentials need in authSource database).
  mongo_openim_password: b3BlbklNMTIz # update to your mongo password encoded in base64, if need empty, you can set to ""

Minio:

Update the minio-root-user and minio-root-password value in minio-secret.yml to your MinIO accessKeyID and secretAccessKey encoded in base64.

apiVersion: v1
kind: Secret
metadata:
  name: openim-minio-secret
type: Opaque
data:
  minio-root-user: cm9vdA== # update to your minio accessKeyID encoded in base64, if need empty, you can set to ""
  minio-root-password: b3BlbklNMTIz # update to your minio secretAccessKey encoded in base64, if need empty, you can set to ""

Kafka:

Update the kafka-password value in kafka-secret.yml to your Kafka password encoded in base64.

apiVersion: v1
kind: Secret
metadata:
  name: openim-kafka-secret
type: Opaque
data:
  kafka-password: b3BlbklNMTIz # update to your kafka password encoded in base64, if need empty, you can set to ""

Apply the secret. Copy Section

kubectl apply -f redis-secret.yml -f minio-secret.yml -f mongo-secret.yml -f kafka-secret.yml

Apply all config Copy Section

kubectl apply -f ./openim-config.yml

Attation: If you use default namespace, you can excute clusterRile.yml to create a cluster role binding for default service account.

Namespace is modify to discovery.yml in openim-config.yml, you can change kubernetes.namespace to your namespace.

Excute clusterRole.yml

kubectl apply -f ./clusterRole.yml

run all deployments and services Copy Section

Note: Ensure that infrastructure services like MinIO, Redis, and Kafka are running before deploying the main applications.

kubectl apply \
  -f openim-api-deployment.yml \
  -f openim-api-service.yml \
  -f openim-crontask-deployment.yml \
  -f openim-rpc-user-deployment.yml \
  -f openim-rpc-user-service.yml \
  -f openim-msggateway-deployment.yml \
  -f openim-msggateway-service.yml \
  -f openim-push-deployment.yml \
  -f openim-push-service.yml \
  -f openim-msgtransfer-service.yml \
  -f openim-msgtransfer-deployment.yml \
  -f openim-rpc-conversation-deployment.yml \
  -f openim-rpc-conversation-service.yml \
  -f openim-rpc-auth-deployment.yml \
  -f openim-rpc-auth-service.yml \
  -f openim-rpc-group-deployment.yml \
  -f openim-rpc-group-service.yml \
  -f openim-rpc-friend-deployment.yml \
  -f openim-rpc-friend-service.yml \
  -f openim-rpc-msg-deployment.yml \
  -f openim-rpc-msg-service.yml \
  -f openim-rpc-third-deployment.yml \
  -f openim-rpc-third-service.yml

Verification Copy Section

After deploying the services, verify that everything is running smoothly:

# Check the status of all pods
kubectl get pods

# Check the status of services
kubectl get svc

# Check the status of deployments
kubectl get deployments

# View all resources
kubectl get all

clean all Copy Section

kubectl delete -f ./

Notes: Copy Section

• If you use a specific namespace for your deployment, be sure to append the -n flag to your kubectl commands.

File: docs/contrib/api.md Copy Chapter

Interface Standards Copy Chapter

Our project, OpenIM, adheres to the OpenAPI 3.0 interface standards.

Chinese translation: OpenAPI Specification Chinese Translation

File: docs/contrib/bash-log.md Copy Chapter

OpenIM Logging System: Design and Usage Copy Chapter

PATH: scripts/lib/logging.sh

Introduction Copy Section

OpenIM, an intricate project, requires a robust logging mechanism to diagnose issues, maintain system health, and provide insights. A custom-built logging system embedded within OpenIM ensures consistent and structured logs. Let's delve into the design of this logging system and understand its various functions and their usage scenarios.

Design Overview Copy Section

1. Initialization: The system begins by determining the verbosity level through the OPENIM_VERBOSE variable. If it's not set, a default value of 5 is assigned. This verbosity level dictates the depth of the log details.
2. Log File Setup: Logs are stored in the directory specified by OPENIM_OUTPUT. If this variable isn't explicitly set, it defaults to the _output directory relative to the script location. Each log file is named based on the date to facilitate easy identification.
3. Logging Function: The echo_log() function plays a pivotal role by writing messages to both the console (stdout) and the log file.
4. Logging to a file: The echo_log() function writes to the log file by appending the message to the file. It also adds a timestamp to the message. path: _output/logs/*, Enable logging by default. Set to false to disable. If you wish to turn off output to log files set export ENABLE_LOGGING=flase.

Key Functions & Their Usages Copy Section

1. Error Handling:
   • openim::log::errexit(): Activated when a command exits with an error. It prints a call tree showing the sequence of functions leading to the error and then calls openim::log::error_exit() with relevant information.
   • openim::log::install_errexit(): Sets up the trap for catching errors and ensures that the error handler (errexit) gets propagated to various script constructs like functions, expansions, and subshells.
2. Logging Levels:
   • openim::log::error(): Logs error messages with a timestamp. The log message starts with '!!!' to indicate its severity.
   • openim::log::info(): Provides informational messages. The display of these messages is governed by the verbosity level (OPENIM_VERBOSE).
   • openim::log::progress(): Designed for logging progress messages or creating progress bars.
   • openim::log::status(): Logs status messages with a timestamp, prefixing each entry with '+++' for easy identification.
   • openim::log::success(): Highlights successful operations with a bright green prefix. It's ideal for visually signifying operations that completed successfully.
3. Exit and Stack Trace:
   • openim::log::error_exit(): Logs an error message, dumps the call stack, and exits the script with a specified exit code.
   • openim::log::stack(): Prints out a stack trace, showing the call hierarchy leading to the point where this function was invoked.
4. Usage Information:
   • openim::log::usage() & openim::log::usage_from_stdin(): Both functions provide a mechanism to display usage instructions. The former accepts arguments directly, while the latter reads them from stdin.
5. Test Function:
   • openim::log::test_log(): This function is a test suite to verify that all logging functions are operating as expected.

Usage Scenario Copy Section

Imagine a situation where an OpenIM operation fails, and you need to ascertain the cause. With the logging system in place, you can:

• Check the log file for the specific day to find error messages with the '!!!' prefix.
• View the call tree and stack trace to trace back the sequence of operations leading to the failure.
• Use the verbosity level to filter out unnecessary details and focus on the crux of the issue.

This systematic and structured approach greatly simplifies the debugging process, making system maintenance more efficient.

Conclusion Copy Section

OpenIM's logging system is a testament to the importance of structured and detailed logging in complex projects. By using this logging mechanism, developers and system administrators can streamline troubleshooting and ensure the seamless operation of the OpenIM project.

File: docs/contrib/cicd-actions.md Copy Chapter

Continuous Integration and Automation

Every change on the OpenIM repository, either made through a pull request or direct push, triggers the continuous integration pipelines defined within the same repository. Needless to say, all the OpenIM contributions can be merged until all the checks pass (AKA having green builds).

• Continuous Integration and Automation
  • CI Platforms
    • GitHub Actions
  • Running locally

CI Platforms Copy Chapter

Currently, there are two different platforms involved in running the CI processes:

• GitHub actions
• Drone pipelines on CNCF infrastructure

GitHub Actions Copy Section

All the existing GitHub Actions are defined as YAML files under the .github/workflows directory. These can be grouped into:

• PR Checks. These actions run all the required validations upon PR creation and update. Covering the DCO compliance check, x86_64 test batteries (unit, integration, smoke), and code coverage.
• Repository automation. Currently, it only covers issues and epic grooming.

Everything runs on GitHub's provided runners; thus, the tests are limited to run in x86_64 architectures.

Running locally Copy Chapter

A contributor should verify their changes locally to speed up the pull request process. Fortunately, all the CI steps can be on local environments, except for the publishing ones, through either of the following methods:

User Makefile:

/* Detailed source-code truncated for AI context efficiency. */

How to Use Makefile to Help Contributors Build Projects Quickly 😊

The make help command is a handy tool that provides useful information on how to utilize the Makefile effectively. By running this command, contributors will gain insights into various targets and options available for building projects swiftly.

Here's a breakdown of the targets and options provided by the Makefile:

Targets 😃

1. all: This target runs multiple tasks like tidy, gen, add-copyright, format, lint, cover, and build. It ensures comprehensive project building.
2. build: The primary target that compiles binaries by default. It is particularly useful for creating the necessary executable files.
3. multiarch: A target that builds binaries for multiple platforms. Contributors can specify the desired platforms using the PLATFORMS option.
4. tidy: This target cleans up the go.mod file, ensuring its consistency.
5. vendor: A target that updates the project dependencies based on the go.mod file.
6. style: Checks the code style using tools like fmt, vet, and lint. It ensures a consistent coding style throughout the project.
7. fmt: Formats the code using the go fmt command, ensuring proper indentation and formatting.
8. vet: Runs the go vet command to identify common errors in the code.
9. lint: Validates the syntax and styling of Go source files using a linter.
10. format: Reformats the package sources using gofmt. It excludes the vendor directory if it exists.
11. test: Executes unit tests to ensure the functionality and stability of the code.
12. cover: Performs unit tests and calculates the test coverage of the code.
13. updates: Checks for updates to the project's dependencies specified in the go.mod file.
14. imports: Automatically handles import packages in Go files using the goimports tool.
15. clean: Removes all files generated during the build process, effectively cleaning up the project directory.
16. image: Builds Docker images for the host architecture.
17. image.multiarch: Similar to the image target, but it builds Docker images for multiple platforms. Contributors can specify the desired platforms using the PLATFORMS option.
18. push: Builds Docker images for the host architecture and pushes them to a registry.
19. push.multiarch: Builds Docker images for multiple platforms and pushes them to a registry. Contributors can specify the desired platforms using the PLATFORMS option.
20. tools: Installs the necessary tools or dependencies required by the project.
21. gen: Generates all the required files automatically.
22. swagger: Generates the swagger document for the project.
23. serve-swagger: Serves the swagger specification and documentation.
24. verify-copyright: Verifies the license headers for all project files.
25. add-copyright: Adds copyright headers to the source code files.
26. release: Releases the project, presumably for distribution.
27. help: Displays information about available targets and options.
28. help-all: Shows detailed information about all available targets and options.

Options 😄

1. DEBUG: A boolean option that determines whether or not to generate debug symbols. The default value is 0 (false).
2. BINS: Specifies the binaries to build. By default, it builds all binaries under the cmd directory. Contributors can provide a list of specific binaries using this option.
3. PLATFORMS: Specifies the platforms to build for. The default platforms are linux_arm64 and linux_amd64. Contributors can specify multiple platforms by providing a space-separated list of platform names.
4. V: A boolean option that enables verbose build output when set to 1 (true). The default value is 0 (false).

With these targets and options in place, contributors can efficiently build projects using the Makefile. Happy coding! 🚀😊

File: docs/contrib/code-conventions.md Copy Chapter

Code conventions

• Code conventions
  • POSIX shell
  • Go
  • OpenIM Naming Conventions Guide
    • 1. General File Naming
    • 2. Special File Types
      • a. Script and Markdown Files
      • b. Uppercase Markdown Documentation
    • 3. Directory Naming
    • 4. Configuration Files
    • Best Practices
  • Directory and File Conventions
  • Testing conventions

POSIX shell Copy Chapter

• Style guide

Go Copy Chapter

• Go Code Review Comments
• Effective Go
• Know and avoid Go landmines
• Comment your code.
  • Go's commenting conventions
  • If reviewers ask questions about why the code is the way it is, that's a sign that comments might be helpful.
• Command-line flags should use dashes, not underscores
• Naming
  • Please consider package name when selecting an interface name, and avoid redundancy. For example, storage.Interface is better than storage.StorageInterface.
  • Do not use uppercase characters, underscores, or dashes in package names.
  • Please consider parent directory name when choosing a package name. For example, pkg/controllers/autoscaler/foo.go should say package autoscaler not package autoscalercontroller.
    • Unless there's a good reason, the package foo line should match the name of the directory in which the .go file exists.
    • Importers can use a different name if they need to disambiguate.Ⓜ️

OpenIM Naming Conventions Guide Copy Chapter

Welcome to the OpenIM Naming Conventions Guide. This document outlines the best practices and standardized naming conventions that our project follows to maintain clarity, consistency, and alignment with industry standards, specifically taking cues from the Google Naming Conventions.

1. General File Naming Copy Section

Files within the OpenIM project should adhere to the following rules:

• Both hyphens (-) and underscores (_) are acceptable in file names.
• Underscores (_) are preferred for general files to enhance readability and compatibility.
• For example: data_processor.py, user_profile_generator.go

2. Special File Types Copy Section

a. Script and Markdown Files

• Bash scripts and Markdown files should use hyphens (-) to facilitate better searchability and compatibility in web browsers.
• For example: deploy-script.sh, project-overview.md

b. Uppercase Markdown Documentation

• Markdown files with uppercase names, such as README, may include underscores (_) to separate words if necessary.
• For example: README_SETUP.md, CONTRIBUTING_GUIDELINES.md

3. Directory Naming Copy Section

• Directories must use hyphens (-) exclusively to maintain a clean and organized file structure.
• For example: image-assets, user-data

4. Configuration Files Copy Section

• Configuration files, including but not limited to .yaml files, should use hyphens (-).
• For example: app-config.yaml, logging-config.yaml

Best Practices Copy Section

• Keep names concise but descriptive enough to convey the file's purpose or contents at a glance.
• Avoid using spaces in names; use hyphens or underscores instead to improve compatibility across different operating systems and environments.
• Stick to lowercase naming where possible for consistency and to prevent issues with case-sensitive systems.
• Include version numbers or dates in file names if the file is subject to updates, following the format: project-plan-v1.2.md or backup-2023-03-15.sql.

Directory and File Conventions Copy Chapter

• Avoid generic utility packages. Instead of naming a package "util", choose a name that clearly describes its purpose. For instance, functions related to waiting operations are contained within the wait package, which includes methods like Poll, fully named as wait.Poll.
• All filenames, script files, configuration files, and directories should be in lowercase and use dashes (-) as separators.
• For Go language files, filenames should be in lowercase and use underscores (_).
• Package names should match their directory names to ensure consistency. For example, within the openim-api directory, the Go file should be named openim-api.go, following the convention of using dashes for directory names and aligning package names with directory names.

Testing conventions Copy Chapter

Please refer to TESTING.md document.

2. Official Technical Reference & Guides (openimsdk/docs) Copy Chapter

OpenIMSDK Documentation

This repository contains the source for the official OpenIMSDK documentation. It provides implementation guides and API documentation for OpenIMClientSDK, OpenIMServer, ChatServer, and the server-side Platform API in English and Simplified Chinese.

OpenIMSDK is the umbrella project for the OpenIMClientSDK client SDKs and the OpenIMServer core IM server. ChatServer is the business extension server; it is not presented as a standalone “Chat” product. The source repositories are maintained by the OpenIMSDK organization.

Documentation links Copy Chapter

Documentation scope Copy Chapter

The public documentation currently covers:

• OpenIMSDK concepts, OpenIMServer and ChatServer deployment guidance, and integration workflows
• iOS SDK
• Flutter SDK
• Electron SDK
• JavaScript SDK for lightweight Web and Mini Program runtimes
• JavaScript SDK (WASM) for full Web IM applications and Electron renderer processes
• Platform API, including authentication, users, relationships, groups, conversations, messages, Webhooks, and operational APIs

Only reviewed platforms and pages appear in the public navigation, search index, and sitemap. Draft structures for additional platforms may remain in the repository without being published.

Capabilities marked Enterprise require the corresponding commercial edition or delivery. See the Enterprise edition for product information, or contact [email protected] for licensing and commercial support.

Technology Copy Chapter

The documentation application is built with:

• Next.js and React
• Fumadocs for MDX content integration
• TypeScript
• Tailwind CSS
• pnpm and Corepack

English and Simplified Chinese pages share one audited route structure. Navigation, search indexes, localized SDK packages, and publication metadata are derived from reviewed MDX and structural records.

Local development Copy Chapter

Requirements Copy Section

• Node.js 22.12 or later
• Corepack
• The pnpm version declared in package.json

Start the development server Copy Section

corepack enable
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev

Open the local site at:

• English: http://localhost:3000
• Simplified Chinese: http://localhost:3000/zh

Repository structure Copy Chapter

api/chat/platform-api/  Versioned OpenAPI source documents
app/                    Next.js routes, metadata, search, and sitemap
content/docs/           English SDK and Platform API MDX
content/en/docs/guides/ Reviewed English guide snapshots
content/zh/docs/        Simplified Chinese MDX and guide snapshots
data/structure/         Navigation, ownership, scope, and review records
docs/                   Current architecture and authoring documentation
public/                 Versioned images, brand assets, and downloads
scripts/                Active validation, synchronization, and build tools
src/components/         Documentation and site UI
src/generated/          Committed route, navigation, search, and locale data

Public URLs do not expose internal product-version directories. For example:

/sdk/wasm/overview
└── content/docs/chat/sdk/wasm/overview.mdx

/zh/sdk/wasm/overview
└── content/zh/docs/chat/sdk/wasm/overview.mdx

Generated files are build inputs, not editorial evidence. Documentation facts must be verified against the pinned OpenIMClientSDK declarations, OpenIMServer definitions, OpenAPI documents, or the immutable sources recorded in the relevant audit file.

Authoring and localization Copy Chapter

Read CONTRIBUTING.md and the content authoring guide before changing documentation pages.

The client SDK localization workflow is Chinese-first:

1. Review the complete Simplified Chinese page and its technical evidence.
2. Edit and audit the page manually.
3. Translate the reviewed page into fluent English.
4. Verify API names, parameters, examples, results, events, and links against the target SDK.
5. Publish the English route only after its review record is complete.

Final MDX prose must be reviewed page by page. Scripts may update deterministic structure and generated metadata, but they must not generate or machine-translate final documentation text.

Validation Copy Chapter

Run the complete validation suite before submitting or publishing changes:

pnpm check
pnpm build

pnpm check includes linting, TypeScript validation, content integrity checks, SDK publication audits, example checks, OpenAPI linting, and Platform API tests. pnpm build validates the production application. Local and Docker builds also prepare the standalone server output; managed platforms use their own Next.js runtime.

Frequently used commands:

Configuration Copy Chapter

Copy .env.example to .env.local for local development. The following public environment variables configure canonical URLs and external navigation:

NEXT_PUBLIC_SITE_URL=https://docs.openim.io
NEXT_PUBLIC_WEBSITE_URL=https://openim.io/
NEXT_PUBLIC_ENTERPRISE_URL=https://openim.io/enterprise/
NEXT_PUBLIC_LEGACY_DOCS_URL=https://openim-docs-legacy.vercel.app
NEXT_PUBLIC_GITHUB_URL=https://github.com/openimsdk
NEXT_PUBLIC_EDIT_BASE_URL=https://github.com/openimsdk/docs/edit/main

NEXT_PUBLIC_LEGACY_DOCS_URL controls the archived-documentation link in the global navigation. Leave NEXT_PUBLIC_EDIT_BASE_URL empty if edit links should not be displayed.

Deployment Copy Chapter

Netlify Copy Section

The production site at docs.openim.io is deployed from main through Netlify. netlify.toml fixes the build command, publish directory, Node.js version, and Next.js Runtime in version control.

Every production deployment must reach ready and pass smoke tests for the home pages, SDK and Platform API routes, search, redirects, Sitemap, and Robots. See the deployment audit for the verified production chain.

Vercel Copy Section

The repository includes vercel.json. Configure the production environment variables, import the repository into Vercel, and use the committed pnpm lockfile. Vercel runs:

pnpm install --frozen-lockfile
pnpm build

Docker and standalone Node.js Copy Section

Build and run the maintained container image with:

docker compose up --build

For a direct Node.js deployment:

corepack enable
pnpm install --frozen-lockfile
pnpm build
PORT=3000 HOSTNAME=0.0.0.0 pnpm start

The production server is generated at .next/standalone/server.js.

Contributing Copy Chapter

Contributions that improve correctness, examples, navigation, accessibility, or developer experience are welcome. Pull requests should identify the affected documentation area, the SDK or server evidence used, and the validation commands that were run.

See:

• Contribution guide
• Content authoring rules
• Architecture
• Current publication scope

Support and security Copy Chapter

Use GitHub Issues for reproducible documentation defects and content corrections. For product, deployment, licensing, or commercial support, contact [email protected].

Do not report security vulnerabilities in a public issue. Follow the private reporting process in SECURITY.md.

License Copy Chapter

This documentation project is licensed under the MIT License.