From b6cdf8c88e24eed7b76358d1e86dd28042e4f349 Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Wed, 6 May 2026 23:58:43 +0300
Subject: [PATCH] Add Docker deployment support with compose, entrypoint and
 docs

- Add Dockerfile (pre-built binary) and Dockerfile.source
- Add docker-compose.yml, docker-compose.prod.yml, docker-compose.override.yml
- Add docker-entrypoint.sh with non-root user support
- Add .dockerignore and helper scripts (scripts/docker-build.sh, scripts/docker-run.sh)
- Add docs/en/docker.md with full Docker guide
- Update docs/en/deployment.md and README.md
- Fix src/barabadb/core/config.nim to read BARADB_ADDRESS, BARADB_PORT, BARADB_DATA_DIR from env
- Fix src/barabadb/core/httpserver.nim missing wire import
---
 .dockerignore                    |  55 +++++++++
 Dockerfile                       |  82 ++++++++++---
 Dockerfile.source                |  86 ++++++++++++++
 README.md                        |  36 ++++--
 docker-compose.override.yml      |  16 +++
 docker-compose.prod.yml          | 129 +++++++++++++++++++++
 docker-compose.yml               |  51 ++++++--
 docker-entrypoint.sh             |  41 +++++++
 docs/en/deployment.md            |  65 +++--------
 docs/en/docker.md                | 193 +++++++++++++++++++++++++++++++
 scripts/docker-build.sh          |  27 +++++
 scripts/docker-run.sh            |  46 ++++++++
 src/barabadb/core/config.nim     |  16 +++
 src/barabadb/core/httpserver.nim |   1 +
 14 files changed, 764 insertions(+), 80 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 Dockerfile.source
 create mode 100644 docker-compose.override.yml
 create mode 100644 docker-compose.prod.yml
 create mode 100755 docker-entrypoint.sh
 create mode 100644 docs/en/docker.md
 create mode 100755 scripts/docker-build.sh
 create mode 100755 scripts/docker-run.sh

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..f0ad7c7
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,55 @@
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+
+# Build outputs (keep baradadb and backup for Dockerfile)
+build/*
+!build/baradadb
+!build/backup
+*.exe
+
+# Data & logs
+data/
+wal/
+sstables/
+*.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker самите файлове (не са нужни в контекста)
+Dockerfile*
+docker-compose*
+.dockerignore
+
+# Scripts (ако са само за хост машината)
+scripts/docker-*.sh
+
+# Tests (не са нужни за production build)
+tests/
+benchmarks/
+
+# Examples
+examples/
+
+# Backup файлове
+backup_*.tar.gz
+backup_history.log
diff --git a/Dockerfile b/Dockerfile
index 7eea7d7..3a74b8f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,18 +1,74 @@
-FROM nim:2.2-alpine AS builder
-WORKDIR /build
-COPY baradadb.nimble .
-COPY src/ src/
-RUN nimble install -d -y || true
-RUN nim c -d:release --opt:speed -o:baradadb src/baradadb.nim
+# ┌─────────────────────────────────────────────────────────┐
+# │ BaraDB — Multimodal Database Engine                     │
+# │ Dockerfile (pre-built binary, production-ready)         │
+# └─────────────────────────────────────────────────────────┘
+#
+# Този Dockerfile използва вече компилиран binary от build/.
+# За build от source вижте Dockerfile.source
+#
+# Build:
+#   docker build -t baradb:latest .
+#
+# Run:
+#   docker run -d -p 9472:9472 -p 9470:9470 -p 9471:9471 -v baradb_data:/data baradb:latest
+
+FROM debian:bookworm-slim
+
+LABEL maintainer="BaraDB Team"
+LABEL description="BaraDB — Multimodal Database Engine"
+LABEL version="0.1.0"
+
+# Инсталираме runtime зависимости
+# libpcre3 — нужна за Nim regex (зарежда се динамично)
+# ca-certificates — за TLS връзки
+# wget — за healthcheck
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libpcre3 \
+        ca-certificates \
+        wget \
+        gosu && \
+    rm -rf /var/lib/apt/lists/*
+
+# Създаваме dedicated потребител за сигурност
+RUN groupadd -r -g 1000 baradb && \
+    useradd -r -u 1000 -g baradb baradb
 
-FROM alpine:latest
 WORKDIR /app
-COPY --from=builder /build/baradadb .
-RUN mkdir -p /data
-ENV BARADB_PORT=9000
+
+# Копираме компилираните бинарни файлове
+COPY build/baradadb /app/baradadb
+COPY build/backup /app/backup
+
+# Копираме entrypoint скрипта
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Създаваме data директория и symlink за съвместимост с default dataDir=./data
+RUN mkdir -p /data && chown baradb:baradb /data && \
+    ln -s /data /app/data && chown -h baradb:baradb /app/data
+
+# Environment variables (defaults)
+ENV BARADB_ADDRESS=0.0.0.0
+ENV BARADB_PORT=9472
+# Note: HTTP port = TCP port + 440 (9912 when TCP=9472)
+# Note: WS port   = TCP port + 441 (9913 when TCP=9472)
 ENV BARADB_DATA_DIR=/data
-ENV BARADB_HTTP_PORT=9470
-ENV BARADB_WS_PORT=9471
-EXPOSE 9000 9470 9471
+ENV BARADB_LOG_LEVEL=info
+
+# Expose ports
+# 9472 — Binary wire protocol
+# 9912 — HTTP/REST API (9472 + 440)
+# 9913 — WebSocket      (9472 + 441)
+EXPOSE 9472 9912 9913
+
+# Volume за persistent data
 VOLUME ["/data"]
+
+# Healthcheck
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget -qO- http://localhost:9912/health >/dev/null 2>&1 || exit 1
+
+# Стартираме чрез entrypoint (който пуска като baradb потребител)
+ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["./baradadb"]
diff --git a/Dockerfile.source b/Dockerfile.source
new file mode 100644
index 0000000..0eb7475
--- /dev/null
+++ b/Dockerfile.source
@@ -0,0 +1,86 @@
+# ┌─────────────────────────────────────────────────────────┐
+# │ BaraDB — Multimodal Database Engine                     │
+# │ Dockerfile.source (build from source)                   │
+# └─────────────────────────────────────────────────────────┘
+#
+# Този Dockerfile build-ва BaraDB от source код.
+# ВНИМАНИЕ: Изисква локални nimble пакети (hunos, nimmax), които
+# не са в публичния nimble repository. Преди build трябва да:
+#   1. symlink-нете или копирате hunos/ и nimmax/ в проекта, или
+#   2. копирате ~/.nimble/pkgs2 в builder стейджа.
+#
+# Build:
+#   docker build -f Dockerfile.source -t baradb:latest .
+
+# ─── Stage 1: Builder ─────────────────────────────────────
+FROM nimlang/nim:2.2.2-alpine AS builder
+
+WORKDIR /build
+
+# Инсталираме build зависимости
+RUN apk add --no-cache git gcc musl-dev openssl-dev pcre-dev
+
+# Копираме nimble файл и инсталираме публични зависимости
+COPY baradadb.nimble .
+RUN nimble install -d -y || true
+
+# Копираме целия изходен код
+COPY src/ src/
+COPY *.nim .
+
+# Компилираме release binary
+# Забележка: Ако липсват локални пакети (hunos), този ред ще се провали.
+RUN nim c -d:release --opt:speed -d:ssl -o:baradadb src/baradadb.nim
+
+# Компилираме backup tool
+RUN nim c -d:release -o:backup src/barabadb/core/backup.nim
+
+# ─── Stage 2: Production Runtime ──────────────────────────
+FROM alpine:3.19
+
+LABEL maintainer="BaraDB Team"
+LABEL description="BaraDB — Multimodal Database Engine (source build)"
+LABEL version="0.1.0"
+
+# Инсталираме runtime зависимости
+RUN apk add --no-cache ca-certificates su-exec wget pcre
+
+# Създаваме dedicated потребител за сигурност
+RUN addgroup -g 1000 -S baradb && \
+    adduser -u 1000 -S baradb -G baradb
+
+WORKDIR /app
+
+# Копираме компилираните бинарни файлове
+COPY --from=builder /build/baradadb /app/baradadb
+COPY --from=builder /build/backup /app/backup
+
+# Копираме entrypoint скрипта
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Създаваме data директория и symlink за съвместимост с default dataDir=./data
+RUN mkdir -p /data && chown baradb:baradb /data && \
+    ln -s /data /app/data && chown -h baradb:baradb /app/data
+
+# Environment variables (defaults)
+ENV BARADB_ADDRESS=0.0.0.0
+ENV BARADB_PORT=9472
+ENV BARADB_HTTP_PORT=9470
+ENV BARADB_WS_PORT=9471
+ENV BARADB_DATA_DIR=/data
+ENV BARADB_LOG_LEVEL=info
+
+# Expose ports
+EXPOSE 9472 9470 9471
+
+# Volume за persistent data
+VOLUME ["/data"]
+
+# Healthcheck
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget -q --spider http://localhost:${BARADB_HTTP_PORT}/health || exit 1
+
+# Стартираме чрез entrypoint
+ENTRYPOINT ["docker-entrypoint.sh"]
+CMD ["./baradadb"]
diff --git a/README.md b/README.md
index 21a4a79..f46185d 100644
--- a/README.md
+++ b/README.md
@@ -483,27 +483,47 @@ nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 
 ## Docker Deployment
 
-### Quick Start with Docker
+### Quick Start
 
 ```bash
-docker build -t baradb .
-docker run -p 9472:9472 -p 9470:9470 -p 9471:9471 -v baradb_data:/data baradb
+docker build -t baradb:latest .
+docker compose up -d
 ```
 
-### Docker Compose
+### Docker Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Production-ready image (pre-built binary) |
+| `Dockerfile.source` | Build from source |
+| `docker-compose.yml` | Development |
+| `docker-compose.prod.yml` | Production with TLS, backups, resource limits |
+| `docker-entrypoint.sh` | Container initialization |
+
+### Production
 
 ```bash
-docker-compose up -d
+docker compose -f docker-compose.prod.yml up -d
 ```
 
+See [docs/en/docker.md](docs/en/docker.md) for full Docker documentation.
+
+### Ports
+
+| Port | Description |
+|------|-------------|
+| `9472` | TCP binary protocol |
+| `9912` | HTTP/REST API (TCP port + 440) |
+| `9913` | WebSocket (TCP port + 441) |
+
 ### Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
+| `BARADB_ADDRESS` | `0.0.0.0` | Bind address |
 | `BARADB_PORT` | `9472` | TCP binary protocol port |
-| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API port |
-| `BARADB_WS_PORT` | `9471` | WebSocket port |
-| `BARADB_DATA_DIR` | `./data` | Data directory |
+| `BARADB_DATA_DIR` | `/data` | Data directory |
+| `BARADB_LOG_LEVEL` | `info` | Log level |
 | `BARADB_TLS_ENABLED` | `false` | Enable TLS |
 | `BARADB_CERT_FILE` | — | TLS certificate path |
 | `BARADB_KEY_FILE` | — | TLS private key path |
diff --git a/docker-compose.override.yml b/docker-compose.override.yml
new file mode 100644
index 0000000..c3e5043
--- /dev/null
+++ b/docker-compose.override.yml
@@ -0,0 +1,16 @@
+# BaraDB — Docker Compose Override (автоматично зарежда се от docker compose)
+# Този файл се използва за development настройки когато използвате:
+#   docker compose up -d
+#
+# За production използвайте:
+#   docker compose -f docker-compose.prod.yml up -d
+
+services:
+  baradb:
+    # Development настройки
+    environment:
+      - BARADB_LOG_LEVEL=debug
+
+    # Монтираме изходния код за development (ако работите върху кода)
+    # volumes:
+    #   - ./src:/app/src:ro
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
new file mode 100644
index 0000000..25e9c3e
--- /dev/null
+++ b/docker-compose.prod.yml
@@ -0,0 +1,129 @@
+# BaraDB — Production Docker Compose
+# Usage: docker compose -f docker-compose.prod.yml up -d
+#
+# Препоръчителни стъпки преди production deployment:
+#   1. Създайте TLS сертификати в ./certs/
+#   2. Задайте силен BARADB_JWT_SECRET
+#   3. Настройте firewall правила за портовете
+#   4. Конфигурирайте регулярни backups
+
+services:
+  baradb:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: baradb:latest
+    container_name: baradb
+    hostname: baradb
+    restart: always
+
+    ports:
+      - "9472:9472"   # Binary protocol
+      - "9912:9912"   # HTTP/REST API
+      - "9913:9913"   # WebSocket
+
+    volumes:
+      - baradb_data:/data
+      # TLS сертификати (read-only)
+      - ./certs:/certs:ro
+      # Лог файлове на хоста
+      - ./logs:/var/log/baradb
+
+    environment:
+      # Network
+      - BARADB_ADDRESS=0.0.0.0
+      - BARADB_PORT=9472
+
+      # Storage
+      - BARADB_DATA_DIR=/data
+      - BARADB_MEMTABLE_SIZE_MB=256
+      - BARADB_CACHE_SIZE_MB=512
+
+      # TLS (разкоментирайте когато имате сертификати)
+      # - BARADB_TLS_ENABLED=true
+      # - BARADB_CERT_FILE=/certs/server.crt
+      # - BARADB_KEY_FILE=/certs/server.key
+
+      # Security (ЗАДЪЛЖИТЕЛНО сменете в production!)
+      # - BARADB_AUTH_ENABLED=true
+      # - BARADB_JWT_SECRET=change-me-to-random-32-char-string
+      # - BARADB_RATE_LIMIT_GLOBAL=10000
+      # - BARADB_RATE_LIMIT_PER_CLIENT=1000
+
+      # Logging
+      - BARADB_LOG_LEVEL=warn
+      - BARADB_LOG_FILE=/var/log/baradb/baradb.log
+      - BARADB_LOG_FORMAT=json
+
+      # Performance
+      - BARADB_COMPACTION_INTERVAL_MS=30000
+      - BARADB_WAL_SYNC_INTERVAL_MS=10
+
+    healthcheck:
+      test: ["CMD", "sh", "-c", "wget -qO- http://localhost:9912/health >/dev/null 2>&1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+    # Production resource limits
+    deploy:
+      resources:
+        limits:
+          cpus: '4.0'
+          memory: 8G
+        reservations:
+          cpus: '1.0'
+          memory: 1G
+
+    # Security hardening
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    tmpfs:
+      - /tmp:noexec,nosuid,size=100m
+
+    networks:
+      - baradb_net
+
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "5"
+        labels: "service_name"
+
+  # Опционален: Backup cron job
+  backup:
+    image: baradb:latest
+    container_name: baradb-backup
+    restart: unless-stopped
+    command: >
+      sh -c '
+        while true; do
+          sleep 86400;
+          /app/backup backup --data-dir=/data --output=/backups/baradb_$$(date +%Y%m%d_%H%M%S).tar.gz --level=6;
+          /app/backup cleanup --keep=7;
+        done
+      '
+    volumes:
+      - baradb_data:/data:ro
+      - ./backups:/backups
+    networks:
+      - baradb_net
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+
+volumes:
+  baradb_data:
+    driver: local
+
+networks:
+  baradb_net:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.28.0.0/16
diff --git a/docker-compose.yml b/docker-compose.yml
index 02685f8..ff5cb60 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,23 +1,56 @@
-version: "3.9"
+# BaraDB — Development Docker Compose
+# Usage: docker compose up -d
+
 services:
   baradb:
-    build: .
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: baradb:latest
+    container_name: baradb-dev
+    hostname: baradb
+    restart: unless-stopped
+
     ports:
-      - "9000:9000"
-      - "9470:9470"
-      - "9471:9471"
+      - "9472:9472"   # Binary protocol
+      - "9912:9912"   # HTTP/REST API
+      - "9913:9913"   # WebSocket
+
     volumes:
       - baradb_data:/data
+      # Монтираме WAL директорията отделно за по-добра производителност (по желание)
+      # - baradb_wal:/data/server/wal
+
     environment:
-      - BARADB_PORT=9000
+      - BARADB_ADDRESS=0.0.0.0
+      - BARADB_PORT=9472
       - BARADB_DATA_DIR=/data
-      - BARADB_HTTP_PORT=9470
-      - BARADB_WS_PORT=9471
+      - BARADB_LOG_LEVEL=debug
+
     healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9470/health"]
+      test: ["CMD", "sh", "-c", "wget -qO- http://localhost:9912/health >/dev/null 2>&1"]
       interval: 10s
       timeout: 5s
       retries: 3
+      start_period: 15s
+
+    # Development resource limits (по-леки)
+    deploy:
+      resources:
+        limits:
+          cpus: '2.0'
+          memory: 2G
+        reservations:
+          cpus: '0.5'
+          memory: 256M
+
+    networks:
+      - baradb_net
 
 volumes:
   baradb_data:
+    driver: local
+
+networks:
+  baradb_net:
+    driver: bridge
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
new file mode 100755
index 0000000..3be415b
--- /dev/null
+++ b/docker-entrypoint.sh
@@ -0,0 +1,41 @@
+#!/bin/sh
+set -e
+
+# BaraDB Docker Entrypoint
+# Създава нужните директории и стартира сървъра с правилни настройки
+
+BARADB_DATA_DIR="${BARADB_DATA_DIR:-/data}"
+BARADB_LOG_LEVEL="${BARADB_LOG_LEVEL:-info}"
+BARADB_PORT="${BARADB_PORT:-9472}"
+
+# Създаваме data директорията ако не съществува
+if [ ! -d "$BARADB_DATA_DIR" ]; then
+    echo "Creating data directory: $BARADB_DATA_DIR"
+    mkdir -p "$BARADB_DATA_DIR"
+fi
+
+# Създаваме поддиректории за WAL и SSTables ако не съществуват
+mkdir -p "$BARADB_DATA_DIR/server"
+mkdir -p "$BARADB_DATA_DIR/server/wal"
+mkdir -p "$BARADB_DATA_DIR/server/sstables"
+
+# Създаваме symlink от /app/data към /data ако липсва
+if [ ! -L "/app/data" ]; then
+    ln -s "$BARADB_DATA_DIR" /app/data
+fi
+
+# Правим директорията собственост на baradb потребителя ако сме root
+if [ "$(id -u)" = "0" ]; then
+    chown -R baradb:baradb "$BARADB_DATA_DIR"
+    # Стартираме като baradb потребител (gosu за Debian, su-exec за Alpine)
+    if command -v gosu >/dev/null 2>&1; then
+        exec gosu baradb "$@"
+    elif command -v su-exec >/dev/null 2>&1; then
+        exec su-exec baradb "$@"
+    else
+        echo "Warning: neither gosu nor su-exec found, running as root"
+        exec "$@"
+    fi
+else
+    exec "$@"
+fi
diff --git a/docs/en/deployment.md b/docs/en/deployment.md
index 9185ca3..7de7ab9 100644
--- a/docs/en/deployment.md
+++ b/docs/en/deployment.md
@@ -2,68 +2,33 @@
 
 ## Docker
 
-### Single Node
+За пълно ръководство за Docker deployment вижте [Docker Guide](docker.md).
+
+### Бърз старт
 
 ```bash
 docker build -t baradb:latest .
-docker run -d \
-  --name baradb \
-  -p 9472:9472 \
-  -p 9470:9470 \
-  -p 9471:9471 \
-  -v baradb_data:/data \
-  -e BARADB_DATA_DIR=/data \
-  baradb:latest
+docker compose up -d
 ```
 
-### Docker Compose (Production)
+### Docker Compose файлове
 
-```yaml
-version: "3.9"
-services:
-  baradb:
-    image: baradb:latest
-    ports:
-      - "9472:9472"
-      - "9470:9470"
-      - "9471:9471"
-    volumes:
-      - baradb_data:/data
-      - ./certs:/certs:ro
-    environment:
-      - BARADB_PORT=9472
-      - BARADB_HTTP_PORT=9470
-      - BARADB_WS_PORT=9471
-      - BARADB_DATA_DIR=/data
-      - BARADB_TLS_ENABLED=true
-      - BARADB_CERT_FILE=/certs/server.crt
-      - BARADB_KEY_FILE=/certs/server.key
-      - BARADB_LOG_LEVEL=info
-      - BARADB_MEMTABLE_SIZE_MB=256
-      - BARADB_CACHE_SIZE_MB=512
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9470/health"]
-      interval: 10s
-      timeout: 5s
-      retries: 3
-    restart: unless-stopped
-    deploy:
-      resources:
-        limits:
-          cpus: '4.0'
-          memory: 8G
-        reservations:
-          cpus: '1.0'
-          memory: 1G
+| Файл | Назначение |
+|------|-----------|
+| `docker-compose.yml` | Development |
+| `docker-compose.prod.yml` | Production |
+| `docker-compose.override.yml` | Dev override (автоматично) |
 
-volumes:
-  baradb_data:
+### Production
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
 ```
 
 ### Docker Swarm
 
 ```bash
-docker stack deploy -c docker-compose.yml baradb
+docker stack deploy -c docker-compose.prod.yml baradb
 ```
 
 ## systemd Service
diff --git a/docs/en/docker.md b/docs/en/docker.md
new file mode 100644
index 0000000..dae789b
--- /dev/null
+++ b/docs/en/docker.md
@@ -0,0 +1,193 @@
+# Docker Deployment Guide
+
+Това ръководство описва как да използвате BaraDB с Docker и Docker Compose.
+
+## Бърз старт
+
+```bash
+# Клониране на репото
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+
+# Build на образа
+docker build -t baradb:latest .
+
+# Стартиране с Docker Compose
+docker compose up -d
+
+# Проверка на статуса
+docker compose ps
+docker compose logs -f
+```
+
+## Файлове
+
+| Файл | Описание |
+|------|----------|
+| `Dockerfile` | Мулти-stage production build |
+| `docker-compose.yml` | Development конфигурация |
+| `docker-compose.prod.yml` | Production конфигурация |
+| `docker-compose.override.yml` | Development override (автоматично се зарежда) |
+| `docker-entrypoint.sh` | Entrypoint скрипт за инициализация |
+| `.dockerignore` | Файлове, които да не се копират в образа |
+| `scripts/docker-build.sh` | Helper скрипт за build |
+| `scripts/docker-run.sh` | Helper скрипт за ръчно стартиране |
+
+## Създаване на образ
+
+```bash
+# Стандартен build
+docker build -t baradb:latest .
+
+# Със скрипта
+./scripts/docker-build.sh
+
+# С конкретна версия
+IMAGE_NAME=baradb VERSION=0.1.0 ./scripts/docker-build.sh
+```
+
+## Стартиране
+
+### Development (docker compose)
+
+```bash
+# Стартиране на заден план
+docker compose up -d
+
+# Спиране
+docker compose down
+
+# Спиране и изтриване на volumes (ВНИМАНИЕ — изтрива данните!)
+docker compose down -v
+
+# Преглед на логове
+docker compose logs -f
+```
+
+### Production (docker compose)
+
+```bash
+# Стартиране с production конфигурация
+docker compose -f docker-compose.prod.yml up -d
+
+# Проверка на healthcheck
+docker compose -f docker-compose.prod.yml ps
+```
+
+### Ръчно (docker run)
+
+```bash
+# Със скрипта
+./scripts/docker-run.sh
+
+# Ръчно
+docker run -d \
+  --name baradb \
+  -p 9472:9472 \
+  -p 9470:9470 \
+  -p 9471:9471 \
+  -v baradb_data:/data \
+  -e BARADB_LOG_LEVEL=info \
+  baradb:latest
+```
+
+## Портове
+
+| Порт | Описание |
+|------|----------|
+| `9472` | Binary wire protocol |
+| `9912` | HTTP/REST API (TCP port + 440) |
+| `9913` | WebSocket (TCP port + 441) |
+
+## Environment Variables
+
+| Променлива | Стойност по подразбиране | Описание |
+|------------|--------------------------|----------|
+| `BARADB_ADDRESS` | `0.0.0.0` | Адрес за слушане |
+| `BARADB_PORT` | `9472` | Binary protocol порт |
+| `BARADB_HTTP_PORT` | `9470` | HTTP порт |
+| `BARADB_WS_PORT` | `9471` | WebSocket порт |
+| `BARADB_DATA_DIR` | `/data` | Директория за данни |
+| `BARADB_LOG_LEVEL` | `info` | Ниво на логове |
+
+> **Забележка:** В момента приложението използва built-in стойности. Пълна поддръжка на env променливи се разработва.
+
+## Volumes
+
+| Път в контейнера | Описание |
+|------------------|----------|
+| `/data` | Основна директория за базата данни |
+| `/data/server/wal` | Write-ahead log |
+| `/data/server/sstables` | SSTable файлове |
+
+## Production Checklist
+
+- [ ] Създайте TLS сертификати в `./certs/`
+- [ ] Задайте силен `BARADB_JWT_SECRET`
+- [ ] Настройте firewall правила
+- [ ] Конфигурирайте регулярни backups
+- [ ] Проверете resource limits
+- [ ] Настройте мониторинг (healthcheck, logs)
+
+## TLS в Docker
+
+1. Създайте сертификати:
+```bash
+mkdir -p certs
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout certs/server.key -out certs/server.crt
+```
+
+2. Активирайте в `docker-compose.prod.yml`:
+```yaml
+environment:
+  - BARADB_TLS_ENABLED=true
+  - BARADB_CERT_FILE=/certs/server.crt
+  - BARADB_KEY_FILE=/certs/server.key
+volumes:
+  - ./certs:/certs:ro
+```
+
+## Backup в Docker
+
+```bash
+# Ръчен backup
+docker exec baradb /app/backup backup --data-dir=/data
+
+# Списък на backups
+docker exec baradb /app/backup list
+
+# Възстановяване
+docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
+```
+
+## Troubleshooting
+
+### Контейнерът не стартира
+
+```bash
+# Проверка на логове
+docker compose logs -f baradb
+
+# Проверка на статус
+docker compose ps
+```
+
+### Няма връзка с базата
+
+```bash
+# Проверка дали портовете са експознати
+docker port baradb
+
+# Проверка отвътре
+docker exec baradb wget -qO- http://localhost:9470/health
+```
+
+### Permission denied на /data
+
+Entrypoint скриптът автоматично създава директориите и задава правилните permissions. Ако имате проблем:
+
+```bash
+docker exec baradb ls -la /data
+docker exec baradb chown -R baradb:baradb /data
+```
diff --git a/scripts/docker-build.sh b/scripts/docker-build.sh
new file mode 100755
index 0000000..9507462
--- /dev/null
+++ b/scripts/docker-build.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+set -e
+
+# BaraDB Docker Build Script
+# Изгражда Docker образа с подходящи тагове
+
+IMAGE_NAME="${IMAGE_NAME:-baradb}"
+VERSION="${VERSION:-latest}"
+BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+
+echo "=== Building BaraDB Docker Image ==="
+echo "Image: ${IMAGE_NAME}:${VERSION}"
+echo "Commit: ${GIT_COMMIT}"
+echo ""
+
+docker build \
+  --build-arg BUILD_DATE="${BUILD_DATE}" \
+  --build-arg VCS_REF="${GIT_COMMIT}" \
+  --tag "${IMAGE_NAME}:${VERSION}" \
+  --tag "${IMAGE_NAME}:latest" \
+  --file Dockerfile \
+  .
+
+echo ""
+echo "=== Build Complete ==="
+echo "Run with: docker run -d -p 9472:9472 -p 9470:9470 -p 9471:9471 ${IMAGE_NAME}:${VERSION}"
diff --git a/scripts/docker-run.sh b/scripts/docker-run.sh
new file mode 100755
index 0000000..d7afd1e
--- /dev/null
+++ b/scripts/docker-run.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+set -e
+
+# BaraDB Docker Run Script
+# Улеснява стартирането на BaraDB контейнер с правилни настройки
+
+IMAGE_NAME="${IMAGE_NAME:-baradb:latest}"
+CONTAINER_NAME="${CONTAINER_NAME:-baradb}"
+DATA_DIR="${DATA_DIR:-$(pwd)/data/docker}"
+
+echo "=== Starting BaraDB Container ==="
+echo "Image: ${IMAGE_NAME}"
+echo "Container: ${CONTAINER_NAME}"
+echo "Data directory: ${DATA_DIR}"
+echo ""
+
+# Създаваме локална data директория ако не съществува
+mkdir -p "${DATA_DIR}"
+
+docker run -d \
+  --name "${CONTAINER_NAME}" \
+  --hostname baradb \
+  --restart unless-stopped \
+  -p 9472:9472 \
+  -p 9912:9912 \
+  -p 9913:9913 \
+  -v "${DATA_DIR}:/data" \
+  -e BARADB_ADDRESS=0.0.0.0 \
+  -e BARADB_PORT=9472 \
+  -e BARADB_DATA_DIR=/data \
+  -e BARADB_LOG_LEVEL=info \
+  --health-cmd "wget -q --spider http://localhost:9470/health || exit 1" \
+  --health-interval 15s \
+  --health-timeout 5s \
+  --health-retries 3 \
+  "${IMAGE_NAME}"
+
+echo ""
+echo "=== Container Started ==="
+echo "Logs: docker logs -f ${CONTAINER_NAME}"
+echo "Stop: docker stop ${CONTAINER_NAME}"
+echo ""
+echo "API Endpoints:"
+echo "  Binary Protocol: localhost:9472"
+echo "  HTTP/REST:       http://localhost:9912"
+echo "  WebSocket:       ws://localhost:9913"
diff --git a/src/barabadb/core/config.nim b/src/barabadb/core/config.nim
index 414a0c9..f0fb730 100644
--- a/src/barabadb/core/config.nim
+++ b/src/barabadb/core/config.nim
@@ -1,3 +1,6 @@
+import std/os
+import std/strutils
+
 type
   BaraConfig* = object
     address*: string
@@ -37,3 +40,16 @@ proc defaultConfig*(): BaraConfig =
 
 proc loadConfig*(): BaraConfig =
   result = defaultConfig()
+  # Docker / Environment overrides
+  let envAddress = getEnv("BARADB_ADDRESS", "")
+  if envAddress.len > 0:
+    result.address = envAddress
+  let envPort = getEnv("BARADB_PORT", "")
+  if envPort.len > 0:
+    try:
+      result.port = parseInt(envPort)
+    except ValueError:
+      discard
+  let envDataDir = getEnv("BARADB_DATA_DIR", "")
+  if envDataDir.len > 0:
+    result.dataDir = envDataDir
diff --git a/src/barabadb/core/httpserver.nim b/src/barabadb/core/httpserver.nim
index 4f6fee0..f2681df 100644
--- a/src/barabadb/core/httpserver.nim
+++ b/src/barabadb/core/httpserver.nim
@@ -15,6 +15,7 @@ import ../query/parser
 import ../query/executor
 import ../storage/lsm
 import ../core/mvcc
+import ../protocol/wire
 import ../protocol/ratelimit
 import ../core/websocket
 import jwt as jwtlib