MARKDOWN SOURCE
--- 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='<long-random-secret>' \ 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 <container>`; 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='<long-random-secret>' \ --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.
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 serveinstead 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:
docker build -f Dockerfile.web -t duckle-web .
For a persistent deployment, provide a durable workspace mount and a strong console token:
docker run --rm -p 8080:8080 \
-v /path/to/workspace:/workspace \
-e DUCKLE_CONSOLE_TOKEN='<long-random-secret>' \
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_TOKENskips 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 <container>; 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.
/healthzis intentionally unauthenticated for liveness checks. It returns onlyokand does not reveal console or workspace data.
Example liveness check:
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:
docker run --rm -p 8080:8080 \
-v /path/to/workspace:/workspace \
-e DUCKLE_CONSOLE_TOKEN='<long-random-secret>' \
--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-lanceandduckle-runnerin 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 to1.5.5by default and pre-installshttpfs,azure,sqlite,postgres,mysql,excel,iceberg,delta,ducklake,vss,fts, andinet, 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.spatialis deliberately omitted because of its large GDAL-backed footprint. - Leave
DUCKLE_PYTHON_BINunset in the image. Duckle should use a prepared workspace.venvfirst and fall back topython3onPATHwhen there is no workspace environment. Setting the variable overrides that resolution and can silently ignore the workspace interpreter; an unprepared workspace declaringuv.lockshould fail clearly rather than run with the wrong Python. - The runtime needs Python 3 for
code.python, andlibodbc2for the Linux Teradata/ODBC feature. The builder needs the matching ODBC development library, plusprotocand clang/libclang for sidecar dependencies.
Troubleshooting checklist
- Can't reach the editor: confirm the container is running, port
8080is published, and the reverse proxy targets the container's HTTP port. Check/healthzfor liveness. - 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_TOKENand recreate the container. - Pipelines or files disappear after recreation: verify that the intended host volume is mounted at
/workspaceand that the host directory is persistent and writable. - 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
LOADautoinstalls its extension, especially under external-I/O restrictions. - Python code uses the wrong interpreter: remove any image-level
DUCKLE_PYTHON_BINoverride and ensure the workspace.venvis prepared for the runtime platform. - Image build is killed during Rust linking: preserve the sequential
duckle-lancethenduckle-runnerrelease 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:
webis the browser editor;serveis the scheduler-capable runner mode.