docs(podman): clarify Podman Machine deployment (#8569)

* docs(podman): clarify Podman Machine deployment

* style(podman): format guidance and regression test
This commit is contained in:
Shixi Li
2026-07-28 06:06:41 +08:00
committed by GitHub
parent 68095ad13d
commit 82bed08404
12 changed files with 294 additions and 72 deletions

View File

@@ -235,8 +235,9 @@ NODE_ENV=production
# Container runtime — controls startup script behavior (permissions, advice).
# Values: docker | podman | Default: docker
# Set to "podman" when running under rootless Podman so the entrypoint
# gives the correct fix instructions (podman unshare chown vs sudo chown).
# Set to "podman" for any Podman topology. The entrypoint cannot determine
# whether the engine is local or reached through Podman Machine, so it prints
# topology-neutral guidance and links contrib/podman/README.md.
CONTAINER_HOST=docker
# Container runtime override for skill sandboxing.

View File

@@ -833,18 +833,22 @@ devbox run npm run dev
**🦭 Podman**
```bash
# 1. Build the image
podman build --target runner-base -t omniroute:base .
# 1. Prepare the bind-mounted data directory
mkdir -p data
# 2. Fix data directory permissions for rootless Podman
mkdir -p data && podman unshare chown 1000:1000 ./data
# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data
# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d
podman compose --profile base up -d --build
```
📖 [Podman Guide](contrib/podman/README.md) — Quadlet setup, podman-compose, Quadlet.
On macOS or Windows, Podman uses a remote Podman Machine: skip `podman unshare` and
follow the [topology-specific data directory guidance](contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Podman Guide](contrib/podman/README.md) — Compose builds, Podman Machine, and
Linux/systemd Quadlet setup.
**⚡ Faster / leaner install (skip the native build)**

View File

@@ -0,0 +1 @@
- **fix(docker):** Podman deployment guidance now distinguishes local Linux rootless engines from macOS/Windows Podman Machine, corrects Quadlet and local-build instructions, and avoids unsupported remote-client `podman unshare` hints ([#8497](https://github.com/diegosouzapw/OmniRoute/issues/8497)).

View File

@@ -1,10 +1,24 @@
# Podman Deployment
Run OmniRoute with Podman via **Quadlet** (systemd integration) or **podman compose**.
Run OmniRoute with **podman compose** on Linux, macOS, or Windows, or with
**Quadlet** on a Linux host that runs systemd.
---
## Option A: Quadlet (recommended)
## Choose the deployment path
- **Linux with a local Podman engine and user systemd:** Compose or Quadlet.
- **macOS or Windows:** Compose. Podman runs containers in a remote Linux VM
managed by Podman Machine; host-side `systemctl` and `podman unshare` do not
operate on that engine.
- **Any other remote Podman connection (including an optional Linux Podman
Machine):** treat it like Podman Machine, not like a local rootless engine.
## Option A: Quadlet (Linux + systemd only)
Use this option only when the Podman engine and user systemd instance run on the
same Linux host. The `systemctl --user` commands below do not configure a Podman
Machine from a macOS or Windows host.
### 1. Build the image
@@ -61,34 +75,19 @@ To follow logs:
journalctl --user -u omniroute -f
```
### 6. Enable on boot
```bash
systemctl --user enable omniroute-redis
systemctl --user enable omniroute
```
The checked-in Quadlet files already contain `[Install]` sections with
`WantedBy=default.target`. The Quadlet generator applies those sections during
`systemctl --user daemon-reload`. Generated Quadlet services are transient
systemd units and must not be enabled with `systemctl enable`.
---
## Option B: podman compose
## Option B: podman compose (all supported host platforms)
The project's `docker-compose.yml` now works with both Docker and Podman.
Just set `CONTAINER_HOST=podman` in `.env` before starting.
### 1. Prepare the data directory
Rootless Podman maps container UIDs into a subordinate range. The
`node` user (UID 1000) inside the container maps to a different UID
on the host, so it cannot write to `./data` owned by your host user.
Fix the ownership **before** starting:
```bash
mkdir -p data
podman unshare chown 1000:1000 ./data
```
### 2. Set the runtime in `.env`
### 1. Set the runtime in `.env`
Make sure `.env` contains:
@@ -96,23 +95,88 @@ Make sure `.env` contains:
CONTAINER_HOST=podman
```
### 3. Start
### 2. Prepare the data directory
The Compose profiles bind-mount `./data` at `/app/data`. Create the directory,
then use the permission guidance for your engine topology below.
```bash
podman compose --profile base up -d
mkdir -p data
```
### 3. Build and start
The application profiles use local image names such as `omniroute:base`; those
are build outputs, not published Docker Hub tags. On the first run, have Compose
build the selected profile:
```bash
podman compose --profile base up -d --build
```
Alternatively, build the matching target explicitly and tell Compose to reuse
that local image:
```bash
podman build --target runner-base -t omniroute:base .
podman compose --profile base up -d --no-build
```
### Profiles
Same profiles as `docker compose`:
| Profile | Command |
| ------------------------------ | ---------------------------------------------------- |
| `base` (no CLIs) | `podman compose --profile base up -d` |
| `web` (+Chromium/Playwright) | `podman compose --profile web up -d` |
| `cli` (+CLI tools) | `podman compose --profile cli up -d` |
| `host` (host-mounted binaries) | `podman compose --profile host up -d` |
| `cliproxyapi` (sidecar) | `podman compose --profile cliproxyapi up -d` |
| Profile | First-run command |
| ------------------------------ | --------------------------------------------- |
| `base` (no CLIs) | `podman compose --profile base up -d --build` |
| `web` (+Chromium/Playwright) | `podman compose --profile web up -d --build` |
| `cli` (+CLI tools) | `podman compose --profile cli up -d --build` |
| `host` (host-mounted binaries) | `podman compose --profile host up -d --build` |
| `cliproxyapi` (sidecar) | `podman compose --profile cliproxyapi up -d` |
---
## Data directory permissions by topology
### Linux with a local rootless Podman engine
Rootless Podman maps container UIDs into a subordinate range. If the container
cannot write to the bind-mounted `./data`, run this **on the Linux host whose
local engine will run the container**:
```bash
podman unshare chown 1000:1000 ./data
```
Use this only when the CLI is connected to a local, non-remote Podman engine.
`podman unshare` is not available with a remote Podman client.
### macOS or Windows with Podman Machine
Podman on macOS and Windows runs the engine inside a Linux VM. The host CLI is a
remote client, so do **not** run `podman unshare` on the macOS or Windows host.
Create `./data` in the host directory shared with the machine and try the
Compose start command above; no ownership change is needed when that mount is
already writable.
If the bind mount is not writable and you do not need direct host access to the
database files, use a Podman-managed named volume with the published image.
Named volumes avoid host-directory UID translation:
```bash
podman volume create omniroute-data
podman run -d --name omniroute \
--env-file .env \
-e DATA_DIR=/app/data \
-p 20128:20128 \
-v omniroute-data:/app/data \
docker.io/diegosouzapw/omniroute:latest
```
For a bind mount that still fails, inspect or repair the shared path from the
Podman Machine side (for example with `podman machine ssh`) according to the
machine provider's mount configuration. A container cannot reliably determine
or repair that host/VM topology for you.
---
@@ -123,6 +187,9 @@ The `docker-compose.yml` uses fully-qualified image names
works with both Docker and Podman without a separate compose file.
The entrypoint script (`check-permissions.sh`) reads `CONTAINER_HOST`
from `.env` to give the correct fix instructions:
from `.env` to choose the runtime guidance:
- **docker**: `sudo chown -R ... ./data`
- **podman**: `podman unshare chown 1000:1000 ./data`
- **podman**: a topology-neutral warning that points back to this guide, because
the container cannot tell whether its engine is local or reached through
Podman Machine.

View File

@@ -6,10 +6,10 @@ Requires=omniroute-redis.service
After=omniroute-redis.service
[Container]
# Use this image if your building locally
# Use this image after building locally
Image=localhost/omniroute:base
# Use this image if you are pulling from Docker Hub
# Image=diegosouzapw/omniroute:base
# Or use the fully qualified published image (there is no published :base tag)
# Image=docker.io/diegosouzapw/omniroute:latest
ContainerName=omniroute

View File

@@ -659,18 +659,23 @@ devbox run npm run dev
**🦭 Podman**
```bash
# 1. Zbuduj obraz
podman build --target runner-base -t omniroute:base .
# 1. Przygotuj katalog danych montowany z hosta
mkdir -p data
# 2. Napraw uprawnienia katalogu danych dla Podmana bez roota
mkdir -p data && podman unshare chown 1000:1000 ./data
# 2. Tylko Linux + lokalny Podman bez roota (nigdy zdalny klient Podman Machine)
podman unshare chown 1000:1000 ./data
# 3. Ustaw środowisko wykonawcze w .env, a następnie uruchom (zobacz contrib/podman/ dla Quadlet)
# 3. Ustaw wskazówkę środowiska, zbuduj lokalny obraz Compose i uruchom
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d
podman compose --profile base up -d --build
```
📖 [Podręcznik Podman](../../../contrib/podman/README.md) — Integracja Quadlet z systemd, podman-compose, Quadlet.
W systemach macOS i Windows Podman korzysta ze zdalnej maszyny Podman Machine:
pomiń `podman unshare` i postępuj zgodnie z
[instrukcjami dla odpowiedniej topologii](../../../contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Podręcznik Podman](../../../contrib/podman/README.md) — budowanie przez
Compose, Podman Machine oraz Quadlet wyłącznie dla Linux/systemd.
**⚡ Szybsza / lżejsza instalacja (pomiń budowanie natywne)**

View File

@@ -658,18 +658,22 @@ devbox run npm run dev
**🦭 Podman**
```bash
# 1. 构建镜像
podman build --target runner-base -t omniroute:base .
# 1. 准备绑定挂载的数据目录
mkdir -p data
# 2. 修复无 Root 权限 Podman 的数据目录权限
mkdir -p data && podman unshare chown 1000:1000 ./data
# 2. 仅限 Linux + 本地无根 Podman(切勿用于远程 Podman Machine 客户端)
podman unshare chown 1000:1000 ./data
# 3. 在 .env 中设置运行时,然后运行(参见 contrib/podman/ 中的 Quadlet)
# 3. 设置运行时提示,构建本地 Compose 镜像并启动
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d
podman compose --profile base up -d --build
```
📖 [Podman 指南](../../contrib/podman/README.md) — Quadlet 设置、podman-compose、Quadlet。
在 macOS 或 Windows 上,Podman 使用远程 Podman Machine:请跳过
`podman unshare`,并按照[针对不同拓扑的数据目录说明](../../../contrib/podman/README.md#data-directory-permissions-by-topology)操作。
📖 [Podman 指南](../../../contrib/podman/README.md) — Compose 构建、Podman Machine
以及仅限 Linux/systemd 的 Quadlet 设置。
<br/>

View File

@@ -981,7 +981,7 @@ CLI_COMPAT_ALL=1
| `DB_BACKUP_MAX_FILES` | `20` | `src/lib/db/backup.ts` | 磁盘上保留的最大 SQLite 备份文件数。覆盖从 Settings → Database backup retention 保存的值。 |
| `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts` | 保留备份的最大天数。`0` 禁用基于时间的清理。覆盖从 Settings → Database backup retention 保存的值。 |
| `OMNIROUTE_TLS_PROXY_URL` | _(未设置)_ | `open-sse/services/chatgptTlsClient.ts` | 覆盖测试用的 TLS sidecar URL。生产环境应保持未设置。 |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | 入口点权限检查的容器运行时提示。在无根 Podman 下设为 `podman`,以便修复指令使用 `podman unshare chown` 而非 `sudo chown`。 |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | 入口点权限检查的容器运行时提示。任何 Podman 拓扑都应设为 `podman`。由于容器无法判断引擎位于本地还是通过 Podman Machine 访问,警告会保持拓扑中立并指向 `contrib/podman/README.md`。 |
| `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | 配额共享消费存储后端:`sqlite`(默认)或 `redis`。 |
| `QUOTA_STORE_REDIS_URL` | _(未设置)_ | `src/lib/quota/storeFactory.ts` | `QUOTA_STORE_DRIVER=redis` 时使用的 Redis 连接字符串(如 `redis://localhost:6379`)。 |
| `QUOTA_SATURATION_THRESHOLD` | `0.5` | `src/lib/quota/enforce.ts` | 池饱和比率(0..1);达到或超过该值时池进入严格模式(不允许借用)。 |

View File

@@ -652,18 +652,22 @@ devbox run npm run dev
**🦭 Podman**
```bash
# 1. 建構映像
podman build --target runner-base -t omniroute:base .
# 1. 準備繫結掛載的資料目錄
mkdir -p data
# 2. 修正無 root Podman 的資料目錄權限
mkdir -p data && podman unshare chown 1000:1000 ./data
# 2. 僅限 Linux + 本機 rootless Podman(切勿用於遠端 Podman Machine 用戶端)
podman unshare chown 1000:1000 ./data
# 3. 在 .env 中設定執行時期,然後執行(參見 contrib/podman/ 中的 Quadlet)
# 3. 設定執行環境提示、建構本機 Compose 映像並啟動
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d
podman compose --profile base up -d --build
```
📖 [Podman Guide](../../contrib/podman/README.md) — Quadlet 設定、podman-compose、Quadlet。
在 macOS 或 Windows 上,Podman 使用遠端 Podman Machine:請略過
`podman unshare`,並依照[各拓撲的資料目錄指引](../../../contrib/podman/README.md#data-directory-permissions-by-topology)操作。
📖 [Podman Guide](../../../contrib/podman/README.md) — Compose 建構、Podman Machine
以及僅限 Linux/systemd 的 Quadlet 設定。
<br/>

View File

@@ -1103,7 +1103,7 @@ Provider quota endpoints, network tunnels (Tailscale, Ngrok, MITM debug proxy),
| `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts` | Maximum age (days) of retained backups. `0` disables age-based pruning. Overrides the value saved from Settings → Database backup retention. |
| `OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS` | `30000` | `src/lib/jobs/backupScheduleJob.ts` | Tick interval (ms) of the server-side job that executes `backup-schedule.json`. Must stay well under the 1-minute cron granularity; values below `5000` or unparseable fall back to `30000`. |
| `OMNIROUTE_TLS_PROXY_URL` | _(unset)_ | `open-sse/services/chatgptTlsClient.ts` | Override the TLS sidecar URL for tests. Production should leave unset. |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | Container runtime hint for the entrypoint permission check. Set to `podman` under rootless Podman so the fix instructions use `podman unshare chown` instead of `sudo chown`. |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | Container runtime hint for the entrypoint permission check. Set to `podman` for any Podman topology. Because the container cannot determine whether the engine is local or reached through Podman Machine, the warning stays topology-neutral and points to `contrib/podman/README.md`. |
| `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | Quota-share consumption store backend: `sqlite` (default) or `redis`. |
| `QUOTA_STORE_REDIS_URL` | _(unset)_ | `src/lib/quota/storeFactory.ts` | Redis connection string used when `QUOTA_STORE_DRIVER=redis` (e.g. `redis://localhost:6379`). |
| `QUOTA_SATURATION_THRESHOLD` | `0.5` | `src/lib/quota/enforce.ts` | Pool saturation ratio (0..1); at/above it the pool enters strict mode (no borrowing). |

View File

@@ -12,9 +12,10 @@ DATA_PATH="${DATA_DIR:-/app/data}"
if [ -d "$DATA_PATH" ] && [ ! -w "$DATA_PATH" ]; then
echo "WARNING: $DATA_PATH is not writable by the current user (UID $(id -u))."
if [ "${CONTAINER_HOST:-}" = "podman" ]; then
echo "Rootless Podman maps container UIDs into a subordinate range."
echo "Run this on the host to fix (using the host-side bind-mount path):"
echo " podman unshare chown -R $(id -u):$(id -g) <host-data-dir>"
echo "Podman bind-mount permissions depend on whether the engine is local or"
echo "reached through Podman Machine; this container cannot determine that topology."
echo "Use the host-side fix for your topology:"
echo " https://github.com/diegosouzapw/OmniRoute/blob/main/contrib/podman/README.md#data-directory-permissions-by-topology"
else
echo "Run this on the Docker host to fix (using the host-side bind-mount path):"
echo " sudo chown -R $(id -u):$(id -g) <host-data-dir>"

View File

@@ -0,0 +1,135 @@
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
function read(relativePath: string): string {
return readFileSync(join(repoRoot, relativePath), "utf8");
}
test("#8497 README limits podman unshare to a local Linux engine", () => {
const readme = read("README.md");
const podmanStart = readme.indexOf("**🦭 Podman**");
const podmanEnd = readme.indexOf("**⚡ Faster / leaner install", podmanStart);
const podmanQuickStart = readme.slice(podmanStart, podmanEnd);
assert.match(podmanQuickStart, /Linux \+ local rootless Podman only/);
assert.match(podmanQuickStart, /podman unshare chown 1000:1000 \.\/data/);
assert.match(podmanQuickStart, /macOS or Windows[\s\S]*remote Podman Machine/);
assert.match(
podmanQuickStart,
/contrib\/podman\/README\.md#data-directory-permissions-by-topology/
);
});
test("#8497 Podman guide separates local engines from Podman Machine", () => {
const guide = read("contrib/podman/README.md");
const localStart = guide.indexOf("### Linux with a local rootless Podman engine");
const machineStart = guide.indexOf("### macOS or Windows with Podman Machine");
const machineEnd = guide.indexOf("\n---", machineStart);
const localGuidance = guide.slice(localStart, machineStart);
const machineGuidance = guide.slice(machineStart, machineEnd);
assert.ok(localStart >= 0, "local rootless Podman guidance must exist");
assert.ok(machineStart > localStart, "Podman Machine guidance must be a distinct section");
assert.match(localGuidance, /podman unshare chown 1000:1000 \.\/data/);
assert.doesNotMatch(machineGuidance, /podman unshare chown/);
assert.match(machineGuidance, /remote client/);
assert.match(machineGuidance, /docker\.io\/diegosouzapw\/omniroute:latest/);
});
test("#8497 Quadlet is Linux/systemd-only and generated units are not enabled", () => {
const guide = read("contrib/podman/README.md");
const appUnit = read("contrib/podman/omniroute.container");
const redisUnit = read("contrib/podman/omniroute-redis.container");
assert.match(guide, /Option A: Quadlet \(Linux \+ systemd only\)/);
assert.doesNotMatch(guide, /systemctl --user enable/);
assert.match(guide, /Generated Quadlet services are transient/);
for (const unit of [appUnit, redisUnit]) {
assert.match(unit, /\[Install\][\s\S]*WantedBy=default\.target/);
}
});
test("#8497 Compose either builds or explicitly reuses the matching local image", () => {
const guide = read("contrib/podman/README.md");
const compose = read("docker-compose.yml");
assert.match(guide, /podman compose --profile base up -d --build/);
assert.match(
guide,
/podman build --target runner-base -t omniroute:base \.[\s\S]*podman compose --profile base up -d --no-build/
);
for (const [service, target, image] of [
["omniroute-base", "runner-base", "omniroute:base"],
["omniroute-web", "runner-web", "omniroute:web"],
["omniroute-cli", "runner-cli", "omniroute:cli"],
["omniroute-host", "runner-base", "omniroute:base"],
]) {
const serviceStart = compose.indexOf(` ${service}:`);
const serviceEnd = compose.indexOf("\n # ── Profile:", serviceStart + 1);
const serviceConfig = compose.slice(serviceStart, serviceEnd === -1 ? undefined : serviceEnd);
assert.ok(serviceStart >= 0, `${service} must exist`);
assert.match(serviceConfig, new RegExp(`target: ${target}`));
assert.match(serviceConfig, new RegExp(`image: ${image}`));
}
assert.match(guide, /podman compose --profile cliproxyapi up -d(?! --build)/);
});
test("#8497 entrypoint emits a topology-neutral Podman hint", () => {
const script = read("scripts/check-permissions.sh");
assert.doesNotMatch(script, /podman unshare/);
assert.doesNotMatch(script, /podman (?:info|machine|system connection)/);
assert.match(script, /engine is local or[\s\S]*Podman Machine/);
assert.match(script, /cannot determine that topology/);
assert.match(script, /contrib\/podman\/README\.md#data-directory-permissions-by-topology/);
});
test("#8497 pull example and environment hints stay topology-safe", () => {
const quadlet = read("contrib/podman/omniroute.container");
const envExample = read(".env.example");
const envReference = read("docs/reference/ENVIRONMENT.md");
assert.match(quadlet, /Image=docker\.io\/diegosouzapw\/omniroute:latest/);
assert.doesNotMatch(quadlet, /diegosouzapw\/omniroute:base/);
for (const source of [envExample, envReference]) {
assert.match(source, /any Podman topology/);
assert.match(source, /cannot determine/);
assert.match(source, /Podman Machine/);
}
});
test("#8497 localized quick starts do not retain the remote-unsafe recipe", () => {
const localizedReadmes = [
{
path: "docs/i18n/zh-CN/README.md",
localOnly: /仅限 Linux \+ 本地无根 Podman/,
},
{
path: "docs/i18n/zh-TW/README.md",
localOnly: /僅限 Linux \+ 本機 rootless Podman/,
},
{
path: "docs/i18n/pl/README.md",
localOnly: /Tylko Linux \+ lokalny Podman bez roota/,
},
];
for (const localized of localizedReadmes) {
const content = read(localized.path);
assert.doesNotMatch(content, /mkdir -p data && podman unshare/);
assert.match(content, localized.localOnly);
assert.match(content, /Podman Machine/);
assert.match(content, /contrib\/podman\/README\.md#data-directory-permissions-by-topology/);
}
const zhEnvironment = read("docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md");
assert.doesNotMatch(zhEnvironment, /修复指令使用 `podman unshare chown`/);
assert.match(zhEnvironment, /任何 Podman 拓扑/);
assert.match(zhEnvironment, /Podman Machine/);
});