Skip to content

docs: add docker compose instructions and mac port forwarding tip to …#781

Merged
qin-ctx merged 1 commit intovolcengine:mainfrom
fengluodb:docs/add-docker-quickstart
Mar 19, 2026
Merged

docs: add docker compose instructions and mac port forwarding tip to …#781
qin-ctx merged 1 commit intovolcengine:mainfrom
fengluodb:docs/add-docker-quickstart

Conversation

@fengluodb
Copy link
Contributor

@fengluodb fengluodb commented Mar 19, 2026

What does this PR do?

This PR updates the Quick Start documentation (both English and Chinese versions) to include instructions for deploying OpenViking as an independent service using Docker Compose.

Additionally, it provides a crucial troubleshooting tip for macOS users who might encounter a Connection reset by peer error when trying to access the service from the host machine.

Changes made:

  1. Renamed section: Changed Installation to Installation & Startup / 安装与启动.
  2. Added Docker Compose instructions: Provided a clear docker-compose.yml template to quickly start the OpenViking server, including volume mappings for configuration (ov.conf) and data.
  3. Added macOS Networking Tip: Added a highlighted tip explaining that OpenViking binds to 127.0.0.1 by default for security reasons. Provided a socat port forwarding solution within the docker-compose.yml command to allow Mac hosts to access the container, without needing to modify the OpenViking security configuration (like setting a root_api_key and exposing to 0.0.0.0).

Why is this needed?

  • Users who want to run OpenViking as a standalone server rather than a python package lacked clear Docker instructions in the quickstart guide.
  • macOS Docker users frequently face the Connection reset issue due to Docker Desktop's networking model combined with OpenViking's strict 127.0.0.1 binding policy when no root key is set. This PR provides a ready-to-use and secure workaround.

Type of change

  • Documentation update

@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.


dingben.db@bytedance.com seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

@qin-ctx qin-ctx merged commit ff751a4 into volcengine:main Mar 19, 2026
1 check was pending
@github-project-automation github-project-automation bot moved this from Backlog to Done in OpenViking project Mar 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants