Skip to main content

​
Installation

Multiple ways to install and run Duckling depending on your needs. The easiest way to run Duckling for production or testing.

​
Prerequisites

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • pnpm 10.0.0+

​
Installation Steps

1

Clone Repository

git clone <repository>
cd duckling
2

Install Dependencies and Build

pnpm install
pnpm run build
This builds all packages in the monorepo:
  • @chittihq/duckling-shared - Shared types
  • @chittihq/duckling-sdk - WebSocket SDK
  • @chittihq/duckling-server - DuckDB server
  • @chittihq/duckling-frontend - Nuxt 4 dashboard
3

Configure Environment

Create your .env file:
cp .env.example .env
Required Variables:
.env
# Database Configuration
MYSQL_CONNECTION_STRING=mysql://user:password@host:port/database
DUCKDB_PATH=data/duckling.db
MYSQL_MAX_CONNECTIONS=5

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

# Sync Configuration
SYNC_INTERVAL_MINUTES=15
BATCH_SIZE=10000
MAX_RETRIES=3
ENABLE_INCREMENTAL_SYNC=true
AUTO_START_SYNC=false
EXCLUDED_TABLES=temp_table,cache_table

# Health Checks
ENABLE_HEALTH_CHECKS=true
HEALTH_CHECK_INTERVAL=60000

# Server
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
Security: Always use strong passwords and API keys. Generate secure values:
openssl rand -hex 32
4

Start Services

docker-compose up -d
Access points:
  • Server API: http://localhost:3001
  • Dashboard: http://localhost:3000
  • MySQL Protocol: localhost:3307
5

Verify Installation

# Check server health
curl http://localhost:3001/health

# Check frontend
curl http://localhost:3000

# View logs
docker-compose logs -f duckdb-server
docker-compose logs -f duckdb-frontend

​
Docker Commands

docker-compose up -d

​
Port Configuration

Default ports defined in docker-compose.yml:
ServiceContainer PortHost PortPurpose
Server (HTTP)30003001REST API
Server (MySQL)33073307MySQL wire protocol
Frontend30003000Nuxt 4 dashboard
Change host ports by editing docker-compose.yml if you have conflicts:
ports:
  - "3002:3000"  # Host:Container

​
Manual Installation

Run Duckling directly on your system without Docker.

​
Prerequisites

  • Node.js 20+
  • pnpm 10.0.0+
  • MySQL database (source)

​
Steps

1

Clone and Install

git clone <repository>
cd duckling
pnpm install
2

Build All Packages

pnpm run build
This builds the monorepo packages in dependency order:
  1. shared - Type definitions
  2. sdk - WebSocket client
  3. server - DuckDB server
  4. frontend - Dashboard
3

Configure Environment

cp .env.example .env
# Edit .env with your settings (see Docker section above)
4

Start Server

pnpm run start:server
Server starts on http://localhost:3000 (or port from PORT env var)
5

Start Frontend (Optional)

In another terminal:
pnpm run start:frontend
Dashboard runs on http://localhost:3000

​
Available Scripts

pnpm run start:server

​
Development Setup

For active development with hot reload.

​
Prerequisites

  • Node.js 20+
  • pnpm 10.0.0+
  • Docker and Docker Compose (recommended)
1

Start Development Environment

docker-compose up -d
Both server and frontend start in development mode with hot reload enabled.
2

Make Code Changes

Edit files in:
  • packages/server/src/ - Server TypeScript files
  • packages/frontend/app/ - Frontend Vue components/pages
  • packages/shared/src/ - Shared types
  • packages/sdk/src/ - SDK source
Changes are automatically detected and applied (no restart needed).
3

View Logs

# Server logs (with hot reload messages)
docker-compose logs -f duckdb-server

# Frontend logs (with HMR messages)
docker-compose logs -f duckdb-frontend
4

Run Commands Inside Container

# Build inside container
docker exec duckling-server pnpm run build:server

# CLI commands
docker exec duckling-server node packages/server/dist/cli.js health
docker exec duckling-server node packages/server/dist/cli.js sync

​
Development without Docker

1

Install Dependencies

pnpm install
2

Start Development Servers

pnpm run dev
3

Access Services

  • Server: http://localhost:3000
  • Frontend: http://localhost:3000 (or configured port)
Hot reload works automatically with nodemon (server) and Nuxt HMR (frontend).

​
Hot Reload Details

ServiceWatcherTriggers OnRestart Needed
Servernodemon.ts files in packages/server/src/Automatic
FrontendNuxt HMR.vue, .ts files in packages/frontend/No (hot module replacement)
Sharedtsc watch.ts files in packages/shared/src/Dependent services restart
When to rebuild containers:
  • Adding/removing npm packages
  • Changing Dockerfiles
  • Updating system dependencies
No rebuild needed for:
  • Code changes (hot reload handles it)
  • .env changes (restart service only)

​
Monorepo Structure

Duckling uses pnpm workspaces for package management: 
duckling/
├── packages/
│   ├── server/          # @chittihq/duckling-server
│   │   ├── src/         # TypeScript source
│   │   ├── dist/        # Compiled JavaScript
│   │   └── package.json
│   ├── frontend/        # @chittihq/duckling-frontend
│   │   ├── app/         # Nuxt pages/components
│   │   └── package.json
│   ├── sdk/             # @chittihq/duckling
│   │   ├── src/         # SDK source
│   │   └── package.json
│   └── shared/          # @chittihq/duckling-shared
│       ├── src/         # Shared types
│       └── package.json
├── pnpm-workspace.yaml  # Workspace config
├── package.json         # Root scripts
└── docker-compose.yml   # Docker services

​
Package Dependencies

  • server → depends on shared
  • frontend → depends on shared, sdk
  • sdk → depends on shared
  • shared → no dependencies (foundation)

​
Next Steps

Quick Start

Follow the quick start guide to configure and use Duckling

Configuration

Learn about environment variables and tuning

API Reference

Explore REST endpoints and WebSocket SDK

Deployment

Production deployment guide

Build docs developers (and LLMs) love

Get started for freeTalk to us