--- name: duckle-web-editor description: Build, deploy, and operate Duckle Web Editor as a self-hosted Docker app. Use when configuring its container, first-run claiming, console credentials, workspace persistence, reverse-proxy exposure, or the separate pipeline scheduler. --- # Duckle Web Editor: self-hosted deployment Use this skill when deploying or maintaining the Duckle Web Editor container. It is an editor and engine running in your environment, not a Duckle-hosted service: workspace data and pipelines stay in the mounted workspace, and execution happens in the container. ## Choose the right runtime - **Web editor only (default):** the image entrypoint runs `duckle-runner web`. It serves the browser editor and runs the engine for interactive work. It does **not** schedule pipelines. - **Scheduler-capable runner:** run `duckle-runner serve` instead when a cron or another orchestrator should trigger pipelines. Do not assume the default web-editor process is a scheduler. The editor frontend is built in browser mode (`DUCKLE_WEB=1`) and served from `/app/dist-web`. The web image includes DuckDB, the Lance/Vortex sidecar, and Python so it has the engine features expected by the desktop app. ## Build and run the editor Build from the Duckle source root, where `Dockerfile.web` is present: ```sh docker build -f Dockerfile.web -t duckle-web . ``` For a persistent deployment, provide a durable workspace mount and a strong console token: ```sh docker run --rm -p 8080:8080 \ -v /path/to/workspace:/workspace \ -e DUCKLE_CONSOLE_TOKEN='' \ duckle-web ``` Then open `http://localhost:8080`. Replace the example host path and token; do not commit or publish a real token. Persist `/workspace` across container replacements because that is where user data and pipelines live. ## First-run claim and access security The server binds to `0.0.0.0` inside the container. Treat the port as a protected administrative console, not as a public unauthenticated web app. - Setting `DUCKLE_CONSOLE_TOKEN` skips the unclaimed window and is the recommended mode for long-lived deployments. - If no token is configured, the console is unclaimed for 15 minutes. Claiming it requires the one-time setup code printed by the server at startup. Read it from `docker logs `; it is generated again on restart and is not stored. Possession of that startup output is the proof that the operator controls the container. - Do not expose the container directly to the public internet. The app serves plain HTTP; terminate TLS at a trusted reverse proxy and restrict access to the console there as appropriate. - `/healthz` is intentionally unauthenticated for liveness checks. It returns only `ok` and does not reveal console or workspace data. Example liveness check: ```sh curl -fsS http://127.0.0.1:8080/healthz ``` ## Run the scheduler instead To run the scheduler-capable server from this image, override its default web entrypoint and mount the same workspace: ```sh docker run --rm -p 8080:8080 \ -v /path/to/workspace:/workspace \ -e DUCKLE_CONSOLE_TOKEN='' \ --entrypoint duckle-runner duckle-web \ serve --host 0.0.0.0 --port 8080 --workspace /workspace ``` Coordinate scheduling separately (for example, with the deployment platform's cron/orchestrator). Do not run this mode just to get the browser editor unless the deployment specifically needs the `serve` behavior. For platform-specific AWS, Azure, or Google Cloud examples, consult Duckle's `website/deploy.html` rather than inventing provider settings. ## Preserve these image/runtime behaviors When editing or troubleshooting the web image, keep these constraints in mind: - Build `duckle-lance` and `duckle-runner` in separate sequential Cargo release invocations. The Lance/Vortex/Arrow dependency graph is large; concurrent fat-LTO release links exceeded the builder's available memory. Keep Cargo cache mounts so retries can reuse downloaded crates and compiled dependencies. - The runner shells out to the DuckDB CLI; it does not need `libduckdb`. The image pins DuckDB to `1.5.5` by default and pre-installs `httpfs`, `azure`, `sqlite`, `postgres`, `mysql`, `excel`, `iceberg`, `delta`, `ducklake`, `vss`, `fts`, and `inet`, so normal pipeline runs do not need to fetch them at runtime. Keep extension installation aligned with the DuckDB version. - Pre-installing extensions matters when workspace policy disables DuckDB external I/O: policy can block autoinstall and raw `INSTALL`, leaving an extension unavailable if it was not baked into the image. `spatial` is deliberately omitted because of its large GDAL-backed footprint. - Leave `DUCKLE_PYTHON_BIN` unset in the image. Duckle should use a prepared workspace `.venv` first and fall back to `python3` on `PATH` when there is no workspace environment. Setting the variable overrides that resolution and can silently ignore the workspace interpreter; an unprepared workspace declaring `uv.lock` should fail clearly rather than run with the wrong Python. - The runtime needs Python 3 for `code.python`, and `libodbc2` for the Linux Teradata/ODBC feature. The builder needs the matching ODBC development library, plus `protoc` and clang/libclang for sidecar dependencies. ## Troubleshooting checklist 1. **Can't reach the editor:** confirm the container is running, port `8080` is published, and the reverse proxy targets the container's HTTP port. Check `/healthz` for liveness. 2. **Claim screen asks for a setup code:** inspect the current container's startup logs. A code from a prior run is stale after restart. For a permanent deployment, configure `DUCKLE_CONSOLE_TOKEN` and recreate the container. 3. **Pipelines or files disappear after recreation:** verify that the intended host volume is mounted at `/workspace` and that the host directory is persistent and writable. 4. **Pipeline says an extension is missing:** check that the extension is in the image's install list and that its DuckDB extension build matches the pinned CLI. Do not assume every DuckDB `LOAD` autoinstalls its extension, especially under external-I/O restrictions. 5. **Python code uses the wrong interpreter:** remove any image-level `DUCKLE_PYTHON_BIN` override and ensure the workspace `.venv` is prepared for the runtime platform. 6. **Image build is killed during Rust linking:** preserve the sequential `duckle-lance` then `duckle-runner` release builds to reduce peak memory use. ## Operational boundaries - Keep user data and pipelines in the mounted workspace; avoid relying on the container's writable layer for durable state. - Keep the console token in the deployment platform's secret store, not in source control, image layers, or shared logs. - Use a reverse proxy for TLS because the container endpoint is plain HTTP. - Keep editor and scheduling responsibilities explicit: `web` is the browser editor; `serve` is the scheduler-capable runner mode.