chore(repo): format codebase and refine docs

2026-03-31 06:08:47 +08:00
1 parent 638b3169eb
commit de296d39d8
@@ -0,0 +1,105 @@
+# Container Engine Guide
+
+Xread ships as a standard OCI image and a Compose stack. Docker, Podman, and `nerdctl` all use the same image, the same `deploy/docker-compose.yml`, the same environment variables, and the same reverse-proxy layout.
+
+## Server Runtimes
+
+| Runtime                   | Single container | Compose stack | Notes                                   |
+| ------------------------- | ---------------- | ------------- | --------------------------------------- |
+| Docker Engine             | Yes              | Yes           | Use `docker run` and `docker compose`   |
+| Podman                    | Yes              | Yes           | Use `podman run` and `podman compose`   |
+| containerd with `nerdctl` | Yes              | Yes           | Use `nerdctl run` and `nerdctl compose` |
+
+## Desktop Wrappers
+
+| Environment     | Single container | Compose stack | Notes                                                                            |
+| --------------- | ---------------- | ------------- | -------------------------------------------------------------------------------- |
+| Docker Desktop  | Yes              | Yes           | Same commands as Docker Engine                                                   |
+| OrbStack        | Yes              | Yes           | Docker-compatible CLI                                                            |
+| Colima          | Yes              | Yes           | Docker-compatible CLI after `docker context` is configured                       |
+| Rancher Desktop | Yes              | Yes           | Use either Docker-compatible CLI or `nerdctl`, depending on how it is configured |
+
+> [!NOTE]
+> The deployment files in [`deploy`](../deploy) stay named `docker-compose.yml` because that filename is still the broadest common denominator across Compose-compatible tooling.
+
+## Single-Container Commands
+
+### Docker-compatible CLIs
+
+These examples work unchanged with:
+
+- Docker Engine
+- Docker Desktop
+- OrbStack
+- Colima with Docker context enabled
+
+```bash
+docker run --rm -p 8081:8081 ghcr.io/xixu-me/xread:latest
+docker run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/search.js
+docker run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/serp.js
+```
+
+### Podman
+
+```bash
+podman run --rm -p 8081:8081 ghcr.io/xixu-me/xread:latest
+podman run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/search.js
+podman run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/serp.js
+```
+
+### nerdctl
+
+```bash
+nerdctl run --rm -p 8081:8081 ghcr.io/xixu-me/xread:latest
+nerdctl run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/search.js
+nerdctl run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/serp.js
+```
+
+## Compose Commands
+
+The stack in [`deploy/docker-compose.yml`](../deploy/docker-compose.yml) works with Compose-compatible CLIs. All engines use the same file and the same variables from [`deploy/.env.example`](../deploy/.env.example).
+
+### Docker / Docker Desktop / OrbStack / Colima
+
+```bash
+docker compose pull
+docker compose up -d
+docker compose ps
+```
+
+### Podman
+
+```bash
+podman compose pull
+podman compose up -d
+podman compose ps
+```
+
+### nerdctl
+
+```bash
+nerdctl compose pull
+nerdctl compose up -d
+nerdctl compose ps
+```
+
+## Shared Deployment Knobs
+
+The deployment model stays the same across engines:
+
+- `PUBLIC_HTTP_PORT` and `PUBLIC_HTTPS_PORT` control the reverse-proxy entrypoints
+- `XREAD_LOOPBACK_HOST` controls whether backend smoke-test ports stay on loopback
+- `XREAD_CRAWL_LOOPBACK_PORT`, `XREAD_SEARCH_LOOPBACK_PORT`, and `XREAD_SERP_LOOPBACK_PORT` control the three backend check ports
+- `R_HOST`, `S_HOST`, and `ACME_EMAIL` control the public reverse-proxy hostnames and certificate email
+
+If your host cannot publish `80` and `443`, use the same fix regardless of engine: set `PUBLIC_HTTP_PORT` and `PUBLIC_HTTPS_PORT` to higher ports, or terminate TLS before the stack.
+
+## Practical Recommendation
+
+Choose the engine that matches your host standard:
+
+- Docker Engine
+- Podman
+- `nerdctl` on containerd
+
+For local development, Docker Desktop, OrbStack, Colima, and Rancher Desktop all work with the same image and Compose stack.