Skip to content
WeftKitBeta

Deployment

WeftKit is distributed as Docker images only. Every deployment option below composes the same published images — weftkit/*:0.1.0 — into a different topology. There is no embedded mode and no "build from source" path: the image IS the distribution.

Deployment Modes

1. Single Engine (Dev / Small Services)

Run one engine on one host. Ideal for development, CI, and small internal tools.

bash
docker run -d \
  --name weftkit-rel \
  -p 20000:20000 \
  -p 9100:9100 \
  -v weftkit-rel-data:/var/lib/weftkit/data \
  weftkit/relational:0.1.0

Best for: local dev, CI integration tests, internal dashboards.

2. Compose Stack (Typical Production)

A multi-engine stack with shared Discovery and a Gateway.

yaml
# docker-compose.yml
services:
  discovery:
    image: weftkit/discovery:0.1.0
    ports: ["20150:20150", "20151:20151"]
    volumes: [discovery-data:/var/lib/weftkit/discovery]
    environment:
      WEFTKIT_DASHBOARD: "true"
      WEFTKIT_NO_AUTH: "true"

  relational:
    image: weftkit/relational:0.1.0
    ports: ["20000:20000", "9100:9100"]
    volumes: [rel-data:/var/lib/weftkit/data]

  inmemory:
    image: weftkit/inmemory:0.1.0
    ports: ["20003:20003", "9101:9100"]
    volumes: [mem-data:/var/lib/weftkit/data]

  gateway:
    image: weftkit/gateway:0.1.0
    ports: ["20100:20100", "20101:20101", "20102:20102", "20103:20103"]
    depends_on: [discovery, relational, inmemory]

  playground:
    image: weftkit/playground:0.1.0
    ports: ["20170:20170"]
    environment:
      WEFTKIT_PLAYGROUND_BIND_ADDRESS: "0.0.0.0:20170"

volumes:
  discovery-data:
  rel-data:
  mem-data:
bash
docker compose up -d

Best for: typical back-ends that need one or two database engines with a single unified entry point.

3. Pooled (Many Connections)

Front one or more engines with the Pool image for connection multiplexing.

yaml
  pool:
    image: weftkit/pool:0.1.0
    ports: ["20160:20160"]
    environment:
      WEFTKIT_POOL_BACKENDS: "relational-primary:20000,relational-replica:20000"
      WEFTKIT_POOL_ROUTING: "least_conn"
    depends_on: [relational-primary]

Best for: SaaS workloads with many clients per engine (thousands of concurrent connections).

4. Kubernetes (StatefulSet)

Each image runs cleanly as a single-container StatefulSet with a PersistentVolumeClaim for /var/lib/weftkit/data.

yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: weftkit-rel
spec:
  replicas: 1
  serviceName: weftkit-rel
  selector:
    matchLabels: { app: weftkit-rel }
  template:
    metadata:
      labels: { app: weftkit-rel }
    spec:
      containers:
        - name: relational
          image: weftkit/relational:0.1.0
          ports:
            - { containerPort: 20000, name: postgres }
            - { containerPort: 9100,  name: native }
          volumeMounts:
            - { name: data, mountPath: /var/lib/weftkit/data }
  volumeClaimTemplates:
    - metadata: { name: data }
      spec:
        accessModes: ["ReadWriteOnce"]
        resources: { requests: { storage: 100Gi } }

Best for: managed platforms, teams already running Kubernetes.

Resource Planning

| Workload | RAM | CPU | Disk | |----------|-----|-----|------| | Development | 512 MB | 1 core | 10 GB | | Production small | 8 GB | 4 cores | 500 GB | | Production large | 64 GB | 16 cores | 4 TB NVMe | | Vector (1M vectors) | 16 GB | 8 cores | 200 GB |

Observability

Every engine image exposes Prometheus metrics on port 9090:

bash
curl http://localhost:9090/metrics

Key metrics:

  • weftkit_query_duration_seconds — p50/p99/p999 histograms
  • weftkit_connections_active — current connections
  • weftkit_buffer_pool_hit_ratio — cache efficiency
  • weftkit_wal_bytes_written_total — write throughput

Upgrades

Pin the image tag, pull the new version, then recreate the container with the same volume:

bash
docker pull weftkit/relational:0.2.0
docker rm -f weftkit-rel
docker run -d \
  --name weftkit-rel \
  -p 20000:20000 -p 9100:9100 \
  -v weftkit-rel-data:/var/lib/weftkit/data \
  weftkit/relational:0.2.0

Engines run WAL recovery on first start against the mounted volume — no manual migration step is required across compatible minor versions.

Next Steps