WebDuck

A self-hosted DuckDB-as-a-Service server with REST API and Web UI. WebDuck is designed for web hosting providers who want to offer their customers a ready-to-use administration interface for DuckDB databases and data analytics — out of the box, just like the database admin tools that come with any hosting package.

Website · Issues · License

Features

• DuckDB storage engine with file-locking for safe concurrent access
• REST API — admin endpoints (project/DB management) + database endpoints (SQL queries)
• Web UI (NiceGUI) — dark mode with yellow/amber theme
• Dashboard — server status cards, live REST traffic monitor (queries/min, active sessions), storage overview with per-project sizes and trash totals
• Trash — soft-delete projects/databases with restore, permanent delete per entry, empty trash
• JWT authentication for admin API, optional project-key auth for database access
• Per-database write protection — lock a database to read-only, independent of passwords: passwords control who may access, write protection controls what may be done to the data. It protects the data only — compacting, deleting and managing passwords in the web UI keep working at any time
• bcrypt password hashing (never plaintext)
• SQL editor — multi-statement support with sequential execution, query history (Alt+Up/Alt+Down, Alt+Enter)
• SQL upload — execute multi-statement SQL scripts from files
• Database compression — reclaims space DuckDB leaves behind after updates/deletes; a hint highlights databases with high fragmentation
• Browse view — tree-based navigation of databases/tables/views with infinite scroll and cell editing
• Import/Export — CSV, Parquet and JSON import via drag & drop, export with browser download
• Project ordering — drag & drop reordering, persisted in .projects.json
• i18n — English (default), German, extensible via PO/Gettext
• Configurable logging — file rotation + console output, independently configurable
• Configurable upload size — max file size for uploads
• FK dependency hints — DROP errors include referenced tables and constraint info
• Docker support out of the box
• YAML configuration

Web UI

Dashboard
Projects	Browse View

Installation

pip (Python)

pip install webduck

Docker

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/autumoswitzerland/Webduck/master/docker-compose.yml

# Set password
export WEBDUCK_ADMIN_PASS=mypassword

# Start - An admin user is created automatically
docker compose up -d

Quick Start

pip

# Initialize - Create an admin user
webduck init

# Create additional admin users (optional)
webduck user add anna secret

# Start server
webduck start

Docker

Docker starts automatically — UI at http://localhost:8998/ui/login. Log in with admin and the password you set.

CLI Commands

Options:

webduck start --host 127.0.0.1 --port 8080 --config /path/to/webduck.yaml
webduck user add anna secret
webduck user add anna secret --config /path/to/webduck.yaml

Configuration

webduck.yaml (generated by webduck init):

icon: "icon.svg"
auth:
  jwt_algorithm: HS256
  jwt_expire_minutes: 60
  jwt_secret: CHANGE-ME-TO-A-SECRET-KEY-IN-PRODUCTION
logging:
  file:
    enabled: true
    level: error
    max_files: 5
    max_size_mb: 10
    query_log: false
    log_dir: log
  console:
    enabled: false
    access_log: false
    level: warning
server:
  data_dir: data
  host: 0.0.0.0
  port: 8998
  max_upload_mb: 256

Security note: Before deploying WebDuck in production, replace jwt_secret in webduck.yaml with a long, random secret (e.g. generated with openssl rand -base64 48). The placeholder value CHANGE-ME-TO-A-SECRET-KEY-IN-PRODUCTION must never be used in production — anyone who knows the secret can forge admin tokens.

Web UI Pages

REST API Reference

Admin API (JWT protected)

All admin endpoints require Authorization: Bearer <jwt_token>. Tokens are signed with the jwt_secret from webduck.yaml — make sure you replaced the placeholder before going to production (see the security note above).

Database API (project-key protected)

All database endpoints require X-Project-Key: <project>:<password>. Databases without a password set are publicly accessible.

Example: Login + Query

# Login
TOKEN=$(curl -s -X POST http://localhost:8998/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}' | jq -r '.token')

# Create project + database
curl -X POST http://localhost:8998/admin/projects \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"myapp"}'

curl -X POST http://localhost:8998/admin/projects/myapp/databases \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"main"}'

# Execute a query via the Database API (no password yet = open)
curl -X POST http://localhost:8998/db/projects/myapp/databases/main/write \
  -H "Content-Type: application/json" \
  -d '{"sql":"CREATE TABLE users (id INT, name VARCHAR); INSERT INTO users VALUES (1, '\''Alice'\'');"}'

# Read (without password — no header needed)
curl -X POST http://localhost:8998/db/projects/myapp/databases/main/query \
  -d '{"sql":"SELECT * FROM users"}'

# Set database password (optional — without password, API is open)
curl -X PUT http://localhost:8998/admin/projects/myapp/databases/main/password \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"password":"dbpass","access_level":"write"}'

# Read (with password)
curl -X POST http://localhost:8998/db/projects/myapp/databases/main/query \
  -H "X-Project-Key: myapp:dbpass" \
  -d '{"sql":"SELECT * FROM users"}'

Docker

Run WebDuck with Docker Compose:

docker compose up -d

WebDuck stores its data in /app/data inside the container. The provided Docker Compose configuration persists this data using the webduck_data volume.

Initialize with:

docker compose exec webduck webduck init

Architecture

FastAPI ──┬── /admin/*   (JWT auth)    → Project/DB management
          ├── /db/*      (project key) → SQL queries + CSV/Parquet/JSON import/export
          ├── /ui/*      (cookie)      → NiceGUI Web UI
          ├── /api/*     (session)     → Internal UI endpoints
          └── /health                  → Health check

• Storage: DuckDB files in data/<project>/<database>.duckdb
• Project order: Persisted in data/.projects.json
• Reserved name: trash is reserved for the soft-delete trash directory — a project directory named trash is not listed as a project
• Auth: Admin passwords in data/.users.json (bcrypt), DB passwords in data/<project>/.project.json
• Write protection: Per-database read-only flag in data/<project>/.project.json; a protected database is always opened read-only by the engine
• User preferences: Stored in data/.user_preferences.json
• Logging: Rotated log files in log/ (configurable), independent console logging
• Concurrency: Per-file reader-writer locks — parallel reads, exclusive writes (DuckDB single-writer model)

Development

git clone https://github.com/autumoswitzerland/Webduck.git
cd webduck
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linter
ruff check src/ tests/

Donate

WebDuck is free and open-source. If you find it useful, consider supporting the development:

License

WebDuck is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see LICENSE for details.

Copyright © 2026 autumo GmbH