Skip to content

MARKDOWN SOURCE

Raw
---
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 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:

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_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:

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-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.