Environment Variables

Duck-UI can be configured using environment variables to customize its behavior, especially for connecting to external DuckDB instances and managing extensions.

Core Configuration Variables

External Connection Settings

These variables allow you to configure Duck-UI to connect to an external DuckDB server (via HTTP API) instead of using the local WASM instance.

Variable	Description	Required	Default	Example
DUCK_UI_EXTERNAL_CONNECTION_NAME	Display name for the external connection in the UI	No	""	"Production DuckDB"
DUCK_UI_EXTERNAL_HOST	Base URL of the external DuckDB HTTP server	No	""	"http://duckdb-server"
DUCK_UI_EXTERNAL_PORT	Port number for the external DuckDB server	No	null	8000
DUCK_UI_EXTERNAL_USER	Username for authentication	No	""	"admin"
DUCK_UI_EXTERNAL_PASS	Password for authentication	No	""	"your-password"
DUCK_UI_EXTERNAL_DATABASE_NAME	Database name to connect to	No	""	"analytics"

Extension Settings

Variable	Description	Required	Default	Example
DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS	Allow loading unsigned DuckDB extensions	No	false	"true"

Security Note

Enabling unsigned extensions may pose security risks. Only enable this in trusted environments.

Usage Examples

Docker - Basic Setup

Run Duck-UI without any external connections (uses local WASM DuckDB):

docker run -p 5522:5522 ghcr.io/ibero-data/duck-ui:latest

Access at: http://localhost:5522

Docker - External DuckDB Connection

Connect Duck-UI to an external DuckDB server:

docker run -p 5522:5522 \
  -e DUCK_UI_EXTERNAL_CONNECTION_NAME="My DuckDB Server" \
  -e DUCK_UI_EXTERNAL_HOST="http://duckdb-server" \
  -e DUCK_UI_EXTERNAL_PORT="8000" \
  -e DUCK_UI_EXTERNAL_USER="username" \
  -e DUCK_UI_EXTERNAL_PASS="password" \
  -e DUCK_UI_EXTERNAL_DATABASE_NAME="my_database" \
  ghcr.io/ibero-data/duck-ui:latest

Docker - With Unsigned Extensions

Enable unsigned extensions for development/testing:

docker run -p 5522:5522 \
  -e DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS="true" \
  ghcr.io/ibero-data/duck-ui:latest

Docker Compose Example

Create a docker-compose.yml file:

services:
  duck-ui:
    image: ghcr.io/ibero-data/duck-ui:latest
    restart: unless-stopped
    ports:
      - "5522:5522"
    environment:
      # External Connection (optional)
      DUCK_UI_EXTERNAL_CONNECTION_NAME: "Production DB"
      DUCK_UI_EXTERNAL_HOST: "http://duckdb-server"
      DUCK_UI_EXTERNAL_PORT: "8000"
      DUCK_UI_EXTERNAL_USER: "viewer"
      DUCK_UI_EXTERNAL_PASS: "secure-password"
      DUCK_UI_EXTERNAL_DATABASE_NAME: "analytics"

      # Extensions (optional)
      DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS: "false"

Start the service:

docker-compose up -d

Connection Types

Duck-UI supports three connection types:

1. WASM (Local)

• Default mode - DuckDB runs entirely in your browser
• No server required - All data processing happens client-side
• Use case: Local data analysis, CSV/Parquet file exploration
• Storage: Origin Private File System (OPFS) for persisted databases

2. OPFS (Persistent)

• Store databases in the browser's Origin Private File System
• Data persists across browser sessions
• Use case: Frequently accessed local databases
• No configuration needed - Available by default in supported browsers

3. External (HTTP)

• Connect to a remote DuckDB server via HTTP API
• Requires DuckDB server with HTTP endpoint
• Use case: Shared databases, production workloads
• Configuration: Use DUCK_UI_EXTERNAL_* environment variables

How Environment Variables Work

Docker Runtime

Environment variables are processed when the Docker container starts:

1. Variables are read from the Docker environment
2. A configuration file is generated at /app/dist/env-config.js
3. The web application loads this configuration on startup
4. External connections appear in the Connections page if configured

Build from Source

For local development or custom builds:

1. Create a .env file in the project root
2. Add your environment variables:

   DUCK_UI_EXTERNAL_HOST=http://localhost:8000
   DUCK_UI_EXTERNAL_CONNECTION_NAME=Local Dev

3. Run the development server:

   npm run dev

Troubleshooting

External Connection Not Appearing

Problem: External connection doesn't show up in Connections page

Solutions:

• Verify all DUCK_UI_EXTERNAL_* variables are set correctly
• Check Docker logs: docker logs <container-name>
• Ensure DUCK_UI_EXTERNAL_HOST includes the protocol (http:// or https://)
• Confirm the external DuckDB server is accessible from the container

Extension Loading Fails

Problem: Extensions fail to load

Solutions:

• Set DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS=true for unsigned extensions
• Check browser console for error messages
• Verify the extension is compatible with DuckDB WASM
• Ensure sufficient browser storage/memory

Connection Timeout

Problem: External connection times out

Solutions:

• Check network connectivity between container and DuckDB server
• Verify DUCK_UI_EXTERNAL_HOST and DUCK_UI_EXTERNAL_PORT are correct
• Ensure firewall rules allow the connection
• Check DuckDB server logs for authentication failures

Next Steps

• Getting Started - Complete installation guide
• Troubleshooting - Common issues and solutions
• GitHub Issues - Report bugs or request features