diff --git a/.env.example b/.env.example
index 477f989d866..3a346383311 100644
--- a/.env.example
+++ b/.env.example
@@ -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.
diff --git a/README.md b/README.md
index cc49454f00e..00394b5fc06 100644
--- a/README.md
+++ b/README.md
@@ -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)**
diff --git a/changelog.d/fixes/pending-podman-machine-guidance.md b/changelog.d/fixes/pending-podman-machine-guidance.md
new file mode 100644
index 00000000000..a71b24db689
--- /dev/null
+++ b/changelog.d/fixes/pending-podman-machine-guidance.md
@@ -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)).
diff --git a/contrib/podman/README.md b/contrib/podman/README.md
index 7ebc6fc9b03..41ee3651d72 100644
--- a/contrib/podman/README.md
+++ b/contrib/podman/README.md
@@ -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.
diff --git a/contrib/podman/omniroute.container b/contrib/podman/omniroute.container
index 846e681a273..31d85257e1c 100644
--- a/contrib/podman/omniroute.container
+++ b/contrib/podman/omniroute.container
@@ -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
diff --git a/docs/i18n/pl/README.md b/docs/i18n/pl/README.md
index e126dd72047..c5a2477b9e3 100644
--- a/docs/i18n/pl/README.md
+++ b/docs/i18n/pl/README.md
@@ -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)**
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
index ee3e9e500f1..eb214f89d0d 100644
--- a/docs/i18n/zh-CN/README.md
+++ b/docs/i18n/zh-CN/README.md
@@ -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 设置。
diff --git a/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md b/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
index de80b7718d1..993c0307283 100644
--- a/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
+++ b/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
@@ -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);达到或超过该值时池进入严格模式(不允许借用)。 |
diff --git a/docs/i18n/zh-TW/README.md b/docs/i18n/zh-TW/README.md
index 5a85f41edf2..ae89305de19 100644
--- a/docs/i18n/zh-TW/README.md
+++ b/docs/i18n/zh-TW/README.md
@@ -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 設定。
diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md
index 625a16209fe..b56757460b4 100644
--- a/docs/reference/ENVIRONMENT.md
+++ b/docs/reference/ENVIRONMENT.md
@@ -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). |
diff --git a/scripts/check-permissions.sh b/scripts/check-permissions.sh
index 0c251166733..87679c04ec0 100755
--- a/scripts/check-permissions.sh
+++ b/scripts/check-permissions.sh
@@ -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) "
+ 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) "
diff --git a/tests/unit/podman-machine-guidance-8497.test.ts b/tests/unit/podman-machine-guidance-8497.test.ts
new file mode 100644
index 00000000000..7e67f0c769e
--- /dev/null
+++ b/tests/unit/podman-machine-guidance-8497.test.ts
@@ -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/);
+});