Skip to main content

​
Quick Start

Get Duckling running with Docker in under 5 minutes.

​
Prerequisites

  • Docker and Docker Compose installed
  • pnpm package manager
  • MySQL database to replicate from

​
Step-by-Step Setup

1

Clone and Build

Clone the repository and build the project:
git clone <repository>
cd duckling
pnpm install && pnpm run build
2

Configure Environment

Copy the example environment file and configure your settings:
cp .env.example .env
Edit .env and set the required values:
# Required: MySQL connection string
MYSQL_CONNECTION_STRING=mysql://user:password@localhost:3306/database

# Required: Security keys (generate with: openssl rand -hex 32)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password
DUCKLING_API_KEY=your-secure-api-key
SESSION_SECRET=generate-with-openssl-rand-hex-32

# Database path
DUCKDB_PATH=data/duckling.db

# Sync configuration
SYNC_INTERVAL_MINUTES=15
BATCH_SIZE=10000
ENABLE_INCREMENTAL_SYNC=true
AUTO_START_SYNC=false
Replace default passwords and API keys with secure values before deploying to production!
3

Start Services

Start the DuckDB server and frontend with Docker Compose:
docker-compose up -d
This starts two services:
  • Server: http://localhost:3001 (backend API)
  • Frontend: http://localhost:3000 (Nuxt 4 dashboard)
  • MySQL Protocol: localhost:3307 (MySQL wire protocol)
4

Verify Installation

Check that both services are running:
curl http://localhost:3001/health
5

Trigger Initial Sync

Open the dashboard at http://localhost:3000 and trigger your first full sync, or use the API:
curl -X POST http://localhost:3001/api/sync/full \
  -H "Authorization: Bearer ${DUCKLING_API_KEY}"
The first sync may take some time depending on your database size. Monitor progress in the dashboard at http://localhost:3000/logs.
6

Query Your Data

Once sync completes, query your replicated data:
curl -X POST http://localhost:3001/api/query \
  -H "Authorization: Bearer ${DUCKLING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT COUNT(*) FROM users"}'

​
What’s Next?

Your Duckling server is now running with:
  • Automatic incremental sync every 15 minutes (if AUTO_START_SYNC=true)
  • REST API endpoints for querying
  • MySQL wire protocol on port 3307
  • Web dashboard for monitoring and queries

Configuration

Learn about all configuration options and tuning parameters

API Reference

Explore REST endpoints and WebSocket SDK

Deployment

Production deployment, security, and backups

Type Support

MySQL to DuckDB type mapping and limitations

​
Docker Services

The docker-compose.yml defines two services:

​
DuckDB Server

  • Container: duckling-server
  • Ports: 3001:3000 (HTTP), 3307:3307 (MySQL protocol)
  • Volumes: ./data:/app/data, ./logs:/app/logs
  • Hot reload enabled for development

​
DuckDB Frontend

  • Container: duckling-frontend
  • Port: 3000:3000
  • Depends on: duckdb-server
  • Hot reload enabled for development

​
Troubleshooting

​
Connection Issues

If you can’t connect to MySQL:
  1. Verify your MYSQL_CONNECTION_STRING is correct
  2. Check MySQL host is reachable from Docker container
  3. Ensure MySQL user has SELECT permissions on target database

​
Sync Errors

Check logs for detailed error messages: 
# Server logs
docker-compose logs -f duckdb-server

# Or view in dashboard
http://localhost:3000/logs

​
Port Conflicts

If ports 3000, 3001, or 3307 are already in use, edit docker-compose.yml: 
ports:
  - "3002:3000"  # Change 3001 to 3002

Build docs developers (and LLMs) love

Get started for freeTalk to us