How KaiwuDB Playground Enables Instant, Isolated Database Learning with Docker

Background

KaiwuDB is a distributed multi‑model database for IoT that supports both time‑series and relational workloads. Traditional local installation requires extensive environment setup, consumes significant resources, and suffers from user interference and static documentation.

Design Goals

Out‑of‑the‑box : a web‑based terminal that runs in the browser.

Environment isolation : each user gets a dedicated Docker container that is created on demand and destroyed after use.

Rich interaction : supports Shell, SQL, and multi‑language code execution.

Core Architecture

Container Management

User sessions map to independent containers under docker/. Lifecycle is handled by controller.go (create/start/stop/destroy), Docker API abstraction in adapter.go, state caching in cache.go, and log forwarding in stream.go.

WebSocket Terminal

terminal.go

forwards keyboard input and command output; code.go runs Python, Java, Bash code. Bidirectional streaming provides low‑latency interaction.

API Handlers

handlers_container.go

: container operations. handlers_course_runtime.go: course runtime management. handlers_sql_ws.go: WebSocket SQL execution. handlers_progress.go: progress save/load. handlers_upgrade.go: version check and upgrade. handlers_system.go: system status.

Course Progress Management

Data models in models.go, progress tracking in progress.go, and service layer in service.go persist progress locally and bind it to container IDs.

SQL Engine

driver.go

abstracts the KaiwuDB driver; manager.go manages SQL sessions and connection pooling, enabling real‑time WebSocket SQL execution with isolated connections per container.

Environment Checks

check.go

validates Docker connectivity and image availability; render.go formats diagnostic results.

Smart Image Selection

Multiple mirror sources are probed, the fastest is chosen, and images are cached locally to reduce pull time.

Online Upgrade

service.go

checks for new releases, downloads binaries, and replaces them, supporting hot or restart upgrades.

Key Technical Points

Docker‑based per‑user isolation.

WebSocket bidirectional streaming for real‑time terminal experience.

State persistence via local files and optional container snapshots.

Multi‑language execution with pre‑installed interpreters inside containers.

Intelligent image source selection and caching.

Resource limits and network segregation for security isolation.

Data Flow

User code → API receives → writes to temporary file in container → executes command → captures output → pushes via WebSocket → displayed in browser

Request create → smart image pull → container creation → port mapping → state cache → returns connection info

Docker Deployment

The Playground container mounts the host Docker socket ( /var/run/docker.sock) to create sibling containers on a dedicated network kwdb-playground-net. Required assets (e.g., tsdb.tar.gz, SQL scripts) are embedded in the binary and injected into course containers at startup, avoiding host path mounts.

git clone https://github.com/kwdb/playground.git
cd playground
docker compose -f docker/playground/docker-compose.yml up -d

Windows users must run the container inside WSL2 or follow docs/docker-deployment.md because the default socket mount works only on Linux/macOS.

After launch, access http://localhost:3006 to use the Playground.

Enhanced Features

Smart image source selection with automatic speed testing.

One‑click online upgrades.

Detailed health checks and diagnostics.

Guided tutorials for first‑time users.

Container pause/resume with progress snapshotting.

Known Issues and Fixes

Container start failure on course page – resolved by upgrading Docker and adding a minimum Docker version check.

Popup cannot be closed after automatic container pull – resolved by refreshing the page.

Java commands fail with exit code 1 in a course – see issue https://github.com/KWDB/playground/issues/128 for details.