From a94e21e0a77602140afa60b4609be61fbff662a2 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:40:10 -0700 Subject: [PATCH] docs(install): update container setup paths --- .dockerignore | 2 +- docker-compose.yml | 2 +- docs/gateway/sandboxing.md | 2 +- docs/install/docker.md | 10 +++++----- docs/install/podman.md | 22 +++++++++++----------- scripts/shell-helpers/README.md | 2 +- scripts/shell-helpers/clawdock-helpers.sh | 2 +- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.dockerignore b/.dockerignore index f24c490e9ad..c6cc1510bcf 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,7 +1,7 @@ .git .worktrees -# Sensitive files – docker-setup.sh writes .env with OPENCLAW_GATEWAY_TOKEN +# Sensitive files – scripts/docker/setup.sh writes .env with OPENCLAW_GATEWAY_TOKEN # into the project root; keep it out of the build context. .env .env.* diff --git a/docker-compose.yml b/docker-compose.yml index c0bffc64458..0a55b342e92 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -16,7 +16,7 @@ services: ## Uncomment the lines below to enable sandbox isolation ## (agents.defaults.sandbox). Requires Docker CLI in the image ## (build with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1) or use - ## docker-setup.sh with OPENCLAW_SANDBOX=1 for automated setup. + ## scripts/docker/setup.sh with OPENCLAW_SANDBOX=1 for automated setup. ## Set DOCKER_GID to the host's docker group GID (run: stat -c '%g' /var/run/docker.sock). # - /var/run/docker.sock:/var/run/docker.sock # group_add: diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index 12650357724..e49372ddc41 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -399,7 +399,7 @@ Security defaults: Docker installs and the containerized gateway live here: [Docker](/install/docker) -For Docker gateway deployments, `docker-setup.sh` can bootstrap sandbox config. +For Docker gateway deployments, `scripts/docker/setup.sh` can bootstrap sandbox config. Set `OPENCLAW_SANDBOX=1` (or `true`/`yes`/`on`) to enable that path. You can override socket location with `OPENCLAW_DOCKER_SOCKET`. Full setup and env reference: [Docker](/install/docker#enable-agent-sandbox-for-docker-gateway-opt-in). diff --git a/docs/install/docker.md b/docs/install/docker.md index aaaa11f9917..ce78993e737 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -32,14 +32,14 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va From the repo root, run the setup script: ```bash - ./docker-setup.sh + ./scripts/docker/setup.sh ``` This builds the gateway image locally. To use a pre-built image instead: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" - ./docker-setup.sh + ./scripts/docker/setup.sh ``` Pre-built images are published at the @@ -139,7 +139,7 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN vs loopback -`docker-setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to +`scripts/docker/setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to `http://127.0.0.1:18789` works with Docker port publishing. - `lan` (default): host browser and host CLI can reach the published gateway port. @@ -180,7 +180,7 @@ See the [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/mai ```bash export OPENCLAW_SANDBOX=1 - ./docker-setup.sh + ./scripts/docker/setup.sh ``` Custom socket path (e.g. rootless Docker): @@ -188,7 +188,7 @@ See the [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/mai ```bash export OPENCLAW_SANDBOX=1 export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock - ./docker-setup.sh + ./scripts/docker/setup.sh ``` The script mounts `docker.sock` only after sandbox prerequisites pass. If diff --git a/docs/install/podman.md b/docs/install/podman.md index 8c8de73bcd2..c21980b5c08 100644 --- a/docs/install/podman.md +++ b/docs/install/podman.md @@ -21,7 +21,7 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image From the repo root, run the setup script. It creates a dedicated `openclaw` user, builds the container image, and installs the launch script: ```bash - ./setup-podman.sh + ./scripts/podman/setup.sh ``` This also creates a minimal config at `~openclaw/.openclaw/openclaw.json` (sets `gateway.mode` to `"local"`) so the Gateway can start without running the wizard. @@ -29,12 +29,12 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image By default the container is **not** installed as a systemd service -- you start it manually in the next step. For a production-style setup with auto-start and restarts, pass `--quadlet` instead: ```bash - ./setup-podman.sh --quadlet + ./scripts/podman/setup.sh --quadlet ``` (Or set `OPENCLAW_PODMAN_QUADLET=1`. Use `--container` to install only the container and launch script.) - **Optional build-time env vars** (set before running `setup-podman.sh`): + **Optional build-time env vars** (set before running `scripts/podman/setup.sh`): - `OPENCLAW_DOCKER_APT_PACKAGES` -- install extra apt packages during image build. - `OPENCLAW_EXTENSIONS` -- pre-install extension dependencies (space-separated names, e.g. `diagnostics-otel matrix`). @@ -64,7 +64,7 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image ## Systemd (Quadlet, optional) -If you ran `./setup-podman.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the openclaw user. The service is enabled and started at the end of setup. +If you ran `./scripts/podman/setup.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the openclaw user. The service is enabled and started at the end of setup. - **Start:** `sudo systemctl --machine openclaw@ --user start openclaw.service` - **Stop:** `sudo systemctl --machine openclaw@ --user stop openclaw.service` @@ -73,11 +73,11 @@ If you ran `./setup-podman.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Po The quadlet file lives at `~openclaw/.config/containers/systemd/openclaw.container`. To change ports or env, edit that file (or the `.env` it sources), then `sudo systemctl --machine openclaw@ --user daemon-reload` and restart the service. On boot, the service starts automatically if lingering is enabled for openclaw (setup does this when loginctl is available). -To add quadlet **after** an initial setup that did not use it, re-run: `./setup-podman.sh --quadlet`. +To add quadlet **after** an initial setup that did not use it, re-run: `./scripts/podman/setup.sh --quadlet`. ## The openclaw user (non-login) -`setup-podman.sh` creates a dedicated system user `openclaw`: +`scripts/podman/setup.sh` creates a dedicated system user `openclaw`: - **Shell:** `nologin` — no interactive login; reduces attack surface. - **Home:** e.g. `/home/openclaw` — holds `~/.openclaw` (config, workspace) and the launch script `run-openclaw-podman.sh`. @@ -98,7 +98,7 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- ## Environment and config -- **Token:** Stored in `~openclaw/.openclaw/.env` as `OPENCLAW_GATEWAY_TOKEN`. `setup-podman.sh` and `run-openclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`). +- **Token:** Stored in `~openclaw/.openclaw/.env` as `OPENCLAW_GATEWAY_TOKEN`. `scripts/podman/setup.sh` and `run-openclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`). - **Optional:** In that `.env` you can set provider keys (e.g. `GROQ_API_KEY`, `OLLAMA_API_KEY`) and other OpenClaw env vars. - **Host ports:** By default the script maps `18789` (gateway) and `18790` (bridge). Override the **host** port mapping with `OPENCLAW_PODMAN_GATEWAY_HOST_PORT` and `OPENCLAW_PODMAN_BRIDGE_HOST_PORT` when launching. - **Gateway bind:** By default, `run-openclaw-podman.sh` starts the gateway with `--bind loopback` for safe local access. To expose on LAN, set `OPENCLAW_GATEWAY_BIND=lan` and configure `gateway.controlUi.allowedOrigins` (or explicitly enable host-header fallback) in `openclaw.json`. @@ -110,7 +110,7 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- - **Ephemeral sandbox tmpfs:** if you enable `agents.defaults.sandbox`, the tool sandbox containers mount `tmpfs` at `/tmp`, `/var/tmp`, and `/run`. Those paths are memory-backed and disappear with the sandbox container; the top-level Podman container setup does not add its own tmpfs mounts. - **Disk growth hotspots:** the main paths to watch are `media/`, `agents//sessions/sessions.json`, transcript JSONL files, `cron/runs/*.jsonl`, and rolling file logs under `/tmp/openclaw/` (or your configured `logging.file`). -`setup-podman.sh` now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts `TMPDIR` only when that base is safe to use; otherwise it falls back to `/var/tmp`, then `/tmp`. The saved tar stays owner-only and is streamed into the target user’s `podman load`, so private caller temp dirs do not block setup. +`scripts/podman/setup.sh` now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts `TMPDIR` only when that base is safe to use; otherwise it falls back to `/var/tmp`, then `/tmp`. The saved tar stays owner-only and is streamed into the target user’s `podman load`, so private caller temp dirs do not block setup. ## Useful commands @@ -122,12 +122,12 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- ## Troubleshooting - **Permission denied (EACCES) on config or auth-profiles:** The container defaults to `--userns=keep-id` and runs as the same uid/gid as the host user running the script. Ensure your host `OPENCLAW_CONFIG_DIR` and `OPENCLAW_WORKSPACE_DIR` are owned by that user. -- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~openclaw/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `setup-podman.sh` creates this file if missing. +- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~openclaw/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this file if missing. - **Rootless Podman fails for user openclaw:** Check `/etc/subuid` and `/etc/subgid` contain a line for `openclaw` (e.g. `openclaw:100000:65536`). Add it if missing and restart. - **Container name in use:** The launch script uses `podman run --replace`, so the existing container is replaced when you start again. To clean up manually: `podman rm -f openclaw`. -- **Script not found when running as openclaw:** Ensure `setup-podman.sh` was run so that `run-openclaw-podman.sh` is copied to openclaw’s home (e.g. `/home/openclaw/run-openclaw-podman.sh`). +- **Script not found when running as openclaw:** Ensure `scripts/podman/setup.sh` was run so that `run-openclaw-podman.sh` is copied to openclaw’s home (e.g. `/home/openclaw/run-openclaw-podman.sh`). - **Quadlet service not found or fails to start:** Run `sudo systemctl --machine openclaw@ --user daemon-reload` after editing the `.container` file. Quadlet requires cgroups v2: `podman info --format '{{.Host.CgroupsVersion}}'` should show `2`. ## Optional: run as your own user -To run the gateway as your normal user (no dedicated openclaw user): build the image, create `~/.openclaw/.env` with `OPENCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.openclaw`. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `setup-podman.sh` and run as the openclaw user so config and process are isolated. +To run the gateway as your normal user (no dedicated openclaw user): build the image, create `~/.openclaw/.env` with `OPENCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.openclaw`. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `scripts/podman/setup.sh` and run as the openclaw user so config and process are isolated. diff --git a/scripts/shell-helpers/README.md b/scripts/shell-helpers/README.md index 302606ee002..b789048a975 100644 --- a/scripts/shell-helpers/README.md +++ b/scripts/shell-helpers/README.md @@ -209,7 +209,7 @@ docker ps - Docker and Docker Compose installed - Bash or Zsh shell -- OpenClaw project (from `docker-setup.sh`) +- OpenClaw project (run `scripts/docker/setup.sh`) ## Development diff --git a/scripts/shell-helpers/clawdock-helpers.sh b/scripts/shell-helpers/clawdock-helpers.sh index 8c491374799..6351aa97f0c 100755 --- a/scripts/shell-helpers/clawdock-helpers.sh +++ b/scripts/shell-helpers/clawdock-helpers.sh @@ -114,7 +114,7 @@ _clawdock_ensure_dir() { echo "Clone it first:" echo "" echo " git clone https://github.com/openclaw/openclaw.git ~/openclaw" - echo " cd ~/openclaw && ./docker-setup.sh" + echo " cd ~/openclaw && ./scripts/docker/setup.sh" echo "" echo "Or set CLAWDOCK_DIR if it's elsewhere:" echo ""