release: v1.2.0 Production GA (single-node)

- known-limitations, deployment runbook, release checklist - prod compose requires JWT secret; BARADB_ENV=production fail-closed - scripts/backup-restore-drill.sh (backup → wipe → restore → verify) - version bump 1.2.0 (nimble, Dockerfile, health, CHANGELOG dated)
2026-07-30 21:52:21 +03:00
parent c66276d72a
commit 09f462f467
18 changed files with 560 additions and 454 deletions
@@ -1,39 +1,145 @@
 # Deployment Guide

+**Production GA (v1.2.0)** is **single-node**. See [known limitations](known-limitations.md).  
+Raft multi-node is [documented](distributed.md) as **experimental**.
+
+## Ports
+
+| Service | Port | Notes |
+|---------|------|--------|
+| Binary wire | `BARADB_PORT` (default 9472) | Clients |
+| HTTP REST | `BARADB_PORT + 440` (9912) | `/health`, `/query`, `/metrics` |
+| WebSocket | `BARADB_PORT + 441` (9913) | |
+| Raft | `BARADB_RAFT_PORT` | Experimental cluster only |
+
+There is **no** `BARADB_HTTP_PORT` — HTTP is always TCP+440.
+
 ## Docker

-За пълно ръководство за Docker deployment вижте [Docker Guide](docker.md).
+See also [Docker Guide](docker.md).

-### Бърз старт
+### Development

 ```bash
 docker build -t baradb:latest .
 docker compose up -d
 ```

-### Docker Compose файлове
+### Production (GA)

-| Файл | Назначение |
-|------|-----------|
+```bash
+export BARADB_JWT_SECRET="$(openssl rand -hex 32)"
+docker compose -f docker-compose.prod.yml up -d --build
+```
+
+- Auth is **on**; compose **fails** if `BARADB_JWT_SECRET` is unset.
+- Binary sets `BARADB_ENV=production` → process refuses empty/placeholder secrets.
+- Image tag: `baradb:1.2.0`.
+
+Optional backup sidecar:
+
+```bash
+docker compose -f docker-compose.prod.yml --profile backup up -d
+```
+
+| Compose file | Role |
+|--------------|------|
 | `docker-compose.yml` | Development |
-| `docker-compose.prod.yml` | Production |
-| `docker-compose.override.yml` | Dev override (автоматично) |
+| `docker-compose.prod.yml` | Production GA |
+| `docker-compose.override.yml` | Local override |

-### Production
+> Note: `deploy.resources` limits apply under Docker Swarm; plain Compose may ignore them.
+
+## Production runbook
+
+### Start (binary)

 ```bash
-docker compose -f docker-compose.prod.yml up -d
+export BARADB_ENV=production
+export BARADB_AUTH_ENABLED=true
+export BARADB_JWT_SECRET="$(openssl rand -hex 32)"   # store securely
+export BARADB_PORT=9472
+export BARADB_DATA_DIR=/var/lib/baradb/data
+export BARADB_LOG_LEVEL=warn
+export BARADB_LOG_FILE=/var/log/baradb/baradb.log
+./build/baradadb
 ```

-### Docker Swarm
+### Stop

 ```bash
-docker stack deploy -c docker-compose.prod.yml baradb
+# systemd
+sudo systemctl stop baradb
+# docker
+docker compose -f docker-compose.prod.yml down
+# foreground: Ctrl+C / SIGTERM
 ```

-## systemd Service
+### Health / metrics

-Create `/etc/systemd/system/baradb.service`:
+```bash
+curl -s http://127.0.0.1:9912/health
+curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9912/metrics
+```
+
+### Auth token (prod)
+
+```bash
+curl -s -X POST http://127.0.0.1:9912/auth \
+  -H 'Content-Type: application/json' \
+  -d "{\"username\":\"admin\",\"password\":\"$BARADB_JWT_SECRET\"}"
+```
+
+### Backup (server stopped or offline-consistent)
+
+Preferred offline / all-databases:
+
+```bash
+./build/backup backup --all-databases \
+  --data-root=/var/lib/baradb/data/databases \
+  --output=/backups/baradb_$(date +%Y%m%d_%H%M%S).tar.gz
+```
+
+Copy archives off-host. Details: [backup.md](backup.md).
+
+### Restore
+
+1. **Stop** BaraDB.
+2. Move aside or empty the data root (keep a copy of the broken dir).
+3. Restore:
+
+```bash
+./build/backup restore --input=/backups/baradb_YYYYMMDD.tar.gz \
+  --all-databases --data-root=/var/lib/baradb/data/databases --force
+```
+
+4. Start BaraDB; verify with a known query.
+
+### Automated drill
+
+```bash
+nim c -o:build/baradadb src/baradadb.nim
+nim c -o:build/backup src/barabadb/core/backup.nim
+./scripts/backup-restore-drill.sh
+```
+
+### Logs
+
+- File: `BARADB_LOG_FILE` (prod compose: `./logs` → `/var/log/baradb`)
+- Docker: `docker logs baradb`
+
+### Data layout
+
+```
+$BARADB_DATA_DIR/
+  databases/
+    default/     # LSM + WAL + schema keys
+  raft/          # only if raft enabled
+```
+
+## systemd
+
+`/etc/systemd/system/baradb.service`:

 ```ini
 [Unit]
@@ -49,16 +155,18 @@ ExecStart=/usr/local/bin/baradadb
 Restart=always
 RestartSec=5

+Environment=BARADB_ENV=production
 Environment=BARADB_PORT=9472
-Environment=BARADB_HTTP_PORT=9470
 Environment=BARADB_DATA_DIR=/var/lib/baradb/data
-Environment=BARADB_LOG_LEVEL=info
+Environment=BARADB_LOG_LEVEL=warn
+Environment=BARADB_AUTH_ENABLED=true
+# Environment=BARADB_JWT_SECRET=  # use EnvironmentFile
+EnvironmentFile=-/etc/baradb/baradb.env

-# Security hardening
 NoNewPrivileges=true
 ProtectSystem=strict
 ProtectHome=true
-ReadWritePaths=/var/lib/baradb/data
+ReadWritePaths=/var/lib/baradb/data /var/log/baradb
 ProtectKernelTunables=true
 ProtectKernelModules=true
 ProtectControlGroups=true
@@ -67,114 +175,47 @@ ProtectControlGroups=true
 WantedBy=multi-user.target
 ```

-Enable and start:
-
 ```bash
 sudo useradd -r -s /bin/false baradb
-sudo mkdir -p /var/lib/baradb/data
-sudo chown -R baradb:baradb /var/lib/baradb
-sudo cp build/baradadb /usr/local/bin/
+sudo mkdir -p /var/lib/baradb/data /var/log/baradb /etc/baradb
+# put BARADB_JWT_SECRET=... in /etc/baradb/baradb.env (mode 600)
 sudo systemctl daemon-reload
 sudo systemctl enable --now baradb
 ```

-## Kubernetes
+## High Availability (experimental)

-### StatefulSet
+Raft multi-node is **not** the v1.2.0 GA tier. See [distributed.md](distributed.md)
+and [known-limitations](known-limitations.md). Use `id@host:port` peer format:

-```yaml
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: baradb
-spec:
-  serviceName: baradb
-  replicas: 3
-  selector:
-    matchLabels:
-      app: baradb
-  template:
-    metadata:
-      labels:
-        app: baradb
-    spec:
-      containers:
-      - name: baradb
-        image: baradb:latest
-        ports:
-        - containerPort: 9472
-          name: binary
-        - containerPort: 9470
-          name: http
-        - containerPort: 9471
-          name: websocket
-        env:
-        - name: BARADB_DATA_DIR
-          value: /data
-        - name: BARADB_RAFT_NODE_ID
-          valueFrom:
-            fieldRef:
-              fieldPath: metadata.name
-        volumeMounts:
-        - name: data
-          mountPath: /data
-  volumeClaimTemplates:
-  - metadata:
-      name: data
-    spec:
-      accessModes: ["ReadWriteOnce"]
-      resources:
-        requests:
-          storage: 100Gi
---
-apiVersion: v1
-kind: Service
-metadata:
-  name: baradb
-spec:
-  selector:
-    app: baradb
-  ports:
-  - port: 9472
-    name: binary
-  - port: 9470
-    name: http
-  - port: 9471
-    name: websocket
-  clusterIP: None
+```bash
+export BARADB_RAFT_ENABLED=true
+export BARADB_RAFT_NODE_ID=n1
+export BARADB_RAFT_PORT=46101
+export BARADB_RAFT_PEERS=n1@127.0.0.1:46101,n2@127.0.0.1:46102,n3@127.0.0.1:46103
+export BARADB_RAFT_CLIENT_PEERS=n1@127.0.0.1:46010,n2@127.0.0.1:46020,n3@127.0.0.1:46030
 ```

-## Reverse Proxy (nginx)
+## Reverse proxy (nginx)
+
+Proxy to **HTTP = TCP+440** (9912 if TCP is 9472):

 ```nginx
 upstream baradb_http {
-    server 127.0.0.1:9470;
+    server 127.0.0.1:9912;
 }
-
 upstream baradb_ws {
-    server 127.0.0.1:9471;
+    server 127.0.0.1:9913;
 }
-
-server {
-    listen 80;
-    server_name db.example.com;
-    return 301 https://$server_name$request_uri;
-}
-
 server {
    listen 443 ssl http2;
    server_name db.example.com;
-
-    ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem;
-
-    location /api/ {
-        proxy_pass http://baradb_http/;
+    location / {
+        proxy_pass http://baradb_http;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
-
    location /ws/ {
        proxy_pass http://baradb_ws/;
        proxy_http_version 1.1;
@@ -184,66 +225,8 @@ server {
 }
 ```

-## High Availability
+## See also

-### 3-Node Raft Cluster
-
-```bash
-# Node 1
-BARADB_RAFT_NODE_ID=node1 \
-BARADB_RAFT_PEERS=node2:9001,node3:9001 \
-./build/baradadb
-
-# Node 2
-BARADB_RAFT_NODE_ID=node2 \
-BARADB_RAFT_PEERS=node1:9001,node3:9001 \
-./build/baradadb
-
-# Node 3
-BARADB_RAFT_NODE_ID=node3 \
-BARADB_RAFT_PEERS=node1:9001,node2:9001 \
-./build/baradadb
-```
-
-## Cloud Deployment
-
-### AWS EC2
-
-Recommended instance: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
-
-```bash
-# User data script
-#!/bin/bash
-apt-get update
-apt-get install -y nim
-wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
-chmod +x baradadb-linux-amd64
-mv baradadb-linux-amd64 /usr/local/bin/baradadb
-
-mkdir -p /data/baradb
-cat > /etc/systemd/system/baradb.service << 'EOF'
-[Unit]
-Description=BaraDB
-After=network.target
-[Service]
-ExecStart=/usr/local/bin/baradadb
-Environment=BARADB_DATA_DIR=/data/baradb
-Restart=always
-[Install]
-WantedBy=multi-user.target
-EOF
-
-systemctl daemon-reload
-systemctl enable --now baradb
-```
-
-### GCP Cloud Run (HTTP only)
-
-```bash
-gcloud run deploy baradb \
-  --image gcr.io/PROJECT/baradb \
-  --port 9470 \
-  --memory 4Gi \
-  --cpu 2 \
-  --max-instances 10
-```
+- [Known limitations](known-limitations.md)
+- [Release checklist](release-checklist.md)
+- [Backup](backup.md) · [Monitoring](monitoring.md) · [Distributed / Raft](distributed.md)
@@ -5,7 +5,7 @@ BaraDB supports distributed deployment with Raft consensus, sharding, and replic
 > ⚠️ **Multi-Database Limitation**
 > The distributed modules (Raft, sharding, and replication) are currently wired to the **`default`** database only. If you use multiple databases (`CREATE DATABASE`, `USE DATABASE`), distributed features do not yet span across them. Each database would need its own cluster setup.

-> **Status (2026-07-30):** Raft C3a (network election), C3b (SQL writes), DDL replication, leader forwarding, log compaction, and metrics are **shipped on `main`**. Design/history: `docs/superpowers/specs/2026-07-30-raft-cluster-status.md`.
+> **Status (2026-07-30):** Raft C3a/C3b + DDL/forward/compact/metrics are **shipped**. Multi-node Raft is **experimental** for v1.2.0 GA (single-node is the production tier). See [known-limitations](known-limitations.md) and `docs/superpowers/specs/2026-07-30-raft-cluster-status.md`.

 ## Raft Consensus

@@ -0,0 +1,55 @@
+# Known Limitations — v1.2.0 Production GA
+
+This page defines **what BaraDB promises** in the v1.2.0 production cut.
+
+| Tier | Meaning |
+|------|---------|
+| **Supported (GA)** | Documented, tested, appropriate for production apps that fit the scope |
+| **Experimental** | Works in tests/ops demos; not a reliability SLA target |
+| **Not supported** | Out of scope; may fail or corrupt assumptions |
+
+## Support matrix
+
+| Area | GA (v1.2.0) | Experimental / later |
+|------|-------------|----------------------|
+| Single-node SQL + LSM storage | **Supported** | — |
+| Schema persistence (tables, indexes) | **Supported** | — |
+| FTS / HNSW / graphs across restart | **Supported** | — |
+| Auth + JWT (when configured) | **Supported** | — |
+| Backup / restore (offline, all-databases) | **Supported** | — |
+| Multi-database (non-Raft) | **Supported** | — |
+| Raft 3-node election + SQL/DDL | **Experimental** | InstallSnapshot SM payload, membership |
+| Raft multi-database | **Not supported** | only `default` |
+| Leader write forwarding | **Experimental** | needs `BARADB_RAFT_CLIENT_PEERS` |
+| Follower linearizable reads | **Not supported** | best-effort after apply |
+| ORC multi-threaded shared LSM | **Not supported** | default is ARC (`nim.cfg`) |
+| Zero-downtime rolling upgrade | **Not supported** | stop → backup → upgrade |
+| Postgres wire protocol | **Not supported** | Bara wire + HTTP |
+
+## Single-node GA (what you can rely on)
+
+- Process crash + WAL recovery for the default durability settings
+- CREATE TABLE / indexes that survive restart (see engine-persistence work)
+- HTTP `/health` and `/metrics` for process liveness
+- Offline backup of `data/databases` and restore onto an empty data root
+
+## Raft (experimental ops)
+
+Documented in [distributed.md](distributed.md). Suitable for learning and careful staging; **not** the v1.2.0 HA product tier.
+
+- SQL DML/DDL on **`default` only**
+- Safe log prefix compact (not full InstallSnapshot)
+- Failover proven in process e2e tests
+
+## Operational requirements
+
+- Set a strong `BARADB_JWT_SECRET` and `BARADB_AUTH_ENABLED=true` in production (see prod compose)
+- Test restores regularly (`scripts/backup-restore-drill.sh`)
+- Do not share one data directory between two running processes
+
+## See also
+
+- [Deployment / runbook](deployment.md)
+- [Backup](backup.md)
+- [Raft cluster status](../superpowers/specs/2026-07-30-raft-cluster-status.md)
+- [Production GA plan](../superpowers/plans/2026-07-30-production-ga.md)
@@ -0,0 +1,57 @@
+# Release checklist — v1.2.0 Production GA
+
+Use before tagging and publishing artifacts.
+
+## Pre-flight
+
+- [ ] Working tree clean on `main`
+- [ ] [Known limitations](known-limitations.md) accurate
+- [ ] `CHANGELOG.md` has dated `## [1.2.0]` (not Unreleased for shipped items)
+- [ ] `baradadb.nimble` version `1.2.0`
+
+## Tests
+
+```bash
+nim c -o:build/baradadb src/baradadb.nim
+nim c -o:build/backup src/barabadb/core/backup.nim
+
+nim c -d:ssl --threads:on --path:src -r tests/test_all.nim
+nim c -d:ssl --threads:on --path:src -r tests/bugfix_test.nim
+nim c -d:ssl --threads:on --path:src -r tests/test_schema_persist.nim
+
+# Ops drill (twice)
+./scripts/backup-restore-drill.sh
+DRILL_PORT=19482 ./scripts/backup-restore-drill.sh
+
+# Optional cluster e2e (experimental tier)
+./tests/raft_e2e_test
+./tests/raft_writes_e2e_test
+```
+
+## Production compose
+
+```bash
+export BARADB_JWT_SECRET="$(openssl rand -hex 32)"
+docker compose -f docker-compose.prod.yml config >/dev/null
+# must fail without secret:
+# (unset BARADB_JWT_SECRET; docker compose -f docker-compose.prod.yml config)
+```
+
+## Artifacts
+
+```bash
+nimble build_release   # or: nim c -d:release -o:build/baradadb src/baradadb.nim
+docker build -t baradb:1.2.0 -t baradb:latest .
+```
+
+## Tag
+
+```bash
+git tag -a v1.2.0 -m "BaraDB v1.2.0 Production GA (single-node)"
+git push origin main --tags
+```
+
+## Post-release
+
+- [ ] Smoke: start prod compose, `/health` → ok, auth required for `/query`
+- [ ] Announce: single-node GA; Raft experimental (link known-limitations)