Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: add Railway one-click deployment guide (#5198)

Zayn Jarvis4bccb1294c01
diff --git a/README.md b/README.md
index 81074ce64..6d84f12be 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,8 @@ English / [中文](README_CN.md) / [日本語](README_JA.md)
[![](https://img.shields.io/badge/license-AGPLv3-white?labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/blob/main/LICENSE)
[![](https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042\&labelColor=black\&style=flat-square)](https://github.com/volcengine/OpenViking/commits/main)
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/openviking)
+
👋 Join our Community
📱 <a href="https://docs.openviking.ai/en/about/01-about-us#lark-group">Lark Group</a> · <a href="https://docs.openviking.ai/en/about/01-about-us#wechat-group">WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3">Discord</a> · <a href="https://x.com/openvikingai">X</a>
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index 26a06c79c..53cfa9f6a 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -301,6 +301,38 @@ After startup, you can access:
- Web Studio: `http://localhost:1933/studio` (same origin as the API)
- Legacy entry point: `http://localhost:1934` (Caddy reverse proxy to 1933, kept for existing deployments)
+### Deploy on Railway
+
+Click the badge below to deploy OpenViking on Railway:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/openviking)
+
+#### Provisioned Resources & Defaults
+
+- **Container Image**: Uses official image `ghcr.io/volcengine/openviking:latest`, listening on port 1933 with an automatically assigned HTTPS domain.
+- **Persistent Storage**: Mounts a persistent volume at `/app/.openviking`. The configured `storage.workspace` (`/app/.openviking/data`) is stored on this volume, ensuring accounts, resources, and vector data persist across redeployments.
+- **Default Configuration**: Preconfigured with OpenAI defaults. `OPENAI_API_KEY` is the only required input during deployment. The admin key `OPENVIKING_ROOT_API_KEY` is generated automatically and viewable in the **Variables** tab.
+
+#### Quick Start (Web Studio)
+
+Initial bootstrap can be completed entirely within the browser:
+
+1. **Set Admin Key**: Copy `OPENVIKING_ROOT_API_KEY` from Railway Variables, open `https://<your-domain>/studio/settings`, and save it.
+2. **Create User**: Navigate to `https://<your-domain>/studio/users` to create your initial account and user. The user API key will be displayed immediately.
+3. **Start Using**: Use this user API key for subsequent access via Web Studio, the `ov` CLI, and SDKs.
+
+#### Configuration Management
+
+- **Initial Configuration**: The template pre-populates `OPENVIKING_CONF_CONTENT` with a complete configuration referencing `${OPENAI_API_KEY}`. This variable is used only on the first startup, when `ov.conf` does not yet exist.
+- **Later Changes**: After the first startup, edit the volume-backed `ov.conf` directly using `railway ssh` or `railway service files upload --overwrite`. Alternatively, delete `ov.conf` and redeploy to regenerate it from the current `OPENVIKING_CONF_CONTENT` value.
+
+#### Pricing & Resource Sizing
+
+- **Recommended Plan**: For continuous hosting, the **Hobby** plan ($5/mo, which includes $5 of usage credits) is recommended. At ~0.5 GB resident memory, typical monthly cost is around $5–$7.
+- **Free/Trial Limitations**: Railway Free plan ($1/mo credit) is insufficient for continuous service. Trial credits ($5 one-time) are suitable for short-term evaluation; note that volumes are purged 30 days after trial expiration.
+
+> **Security Note**: The service is publicly accessible by default. Keep `OPENVIKING_ROOT_API_KEY` confidential and consult the [public access guide](12-public-access.md) before production rollout.
+
### Multi-instance notes
With an embedded vector backend (`local` or `cuvs`), OpenViking holds an exclusive OS file lock on `storage.workspace` by default. The `.openviking.lock` file remains on disk; its presence does not mean a server is running. The OS releases the lock when the server closes it or the process terminates. Do not manually delete a running server's lock file.
diff --git a/docs/images/ov-logo-square.png b/docs/images/ov-logo-square.png
new file mode 100644
index 000000000..a8889d94d
Binary files /dev/null and b/docs/images/ov-logo-square.png differ
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index d2900a371..737eeaeca 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -296,6 +296,38 @@ docker compose up -d
- Web Studio:`http://localhost:1933/studio`(与 API 同源)
- 兼容入口:`http://localhost:1934`(Caddy 反代到 1933,仅为已有部署保留)
+### 部署到 Railway
+
+点击下方按钮一键部署到 Railway:
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/openviking)
+
+#### 预置资源与环境
+
+- **服务镜像**:拉取官方镜像 `ghcr.io/volcengine/openviking:latest`,监听 1933 端口,Railway 自动分配 HTTPS 域名。
+- **持久化存储**:挂载持久卷至 `/app/.openviking`,`storage.workspace` 位于该卷上,保证重新部署后数据与配置不丢失。
+- **默认配置**:默认采用 OpenAI 预设。部署时仅需填写 `OPENAI_API_KEY`;管理员密钥 `OPENVIKING_ROOT_API_KEY` 自动生成,部署完成后可在 Railway 的 **Variables** 标签页查看。
+
+#### 快速初始化(Web Studio)
+
+部署完成后,在浏览器中即可完成首次初始化:
+
+1. **配置管理员密钥**:从 Railway 服务变量中复制 `OPENVIKING_ROOT_API_KEY`,访问 `https://<你的域名>/studio/settings` 并保存。
+2. **创建用户**:进入 `https://<你的域名>/studio/users` 创建首个账户与用户,系统将展示该用户的 API Key。
+3. **开始使用**:后续访问 Web Studio、`ov` CLI 或 SDK 时,均使用上述用户的 API Key。
+
+#### 配置管理
+
+- **首次生成配置**:模板在 `OPENVIKING_CONF_CONTENT` 中预置了完整配置并引用 `${OPENAI_API_KEY}`。该变量仅在首次启动且 `ov.conf` 尚不存在时生效。
+- **后续修改配置**:首次启动后,请通过 `railway ssh` 或 `railway service files upload --overwrite` 直接修改持久卷上的 `ov.conf`;也可以删除 `ov.conf` 后重新部署,让服务按当前 `OPENVIKING_CONF_CONTENT` 重新生成配置文件。
+
+#### 资源与费用参考
+
+- **推荐配置**:长期运行建议选择 **Hobby** 计划($5/月,包含 $5 用量抵扣)。以 ~0.5 GB 常驻内存估算,月均成本通常在 $5–$7 左右。
+- **免费额度说明**:Railway Free 计划($1/月额度)不足以支持服务常驻运行;Trial 赠金适合短期体验评估,额度到期 30 天后持久卷将被清理,请注意按需备份数据。
+
+> **安全提示**:服务部署后默认监听并暴露于公网。请妥善保管 `OPENVIKING_ROOT_API_KEY`,在对外开放前请阅读[公网访问安全指南](12-public-access.md)。
+
### 多实例部署注意事项
使用本地向量后端(`local` 或 `cuvs`)时,OpenViking 默认通过操作系统文件锁独占 `storage.workspace`。`.openviking.lock` 文件会保留在磁盘上,文件存在不代表服务正在运行;正常关闭或进程终止后,操作系统会释放锁。不要手动删除运行中服务的锁文件。