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,250 +1,35 @@
-# Ръководство за Внедряване (Deployment)
+# Deployment Guide (кратко)

-## Docker
+**Production GA v1.2.0** = **single-node**. Виж [known-limitations](known-limitations.md).  
+Пълен runbook: [en/deployment.md](../en/deployment.md).

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

-### Бърз старт
+| Услуга | Порт |
+|--------|------|
+| Wire | `BARADB_PORT` (9472) |
+| HTTP | `BARADB_PORT + 440` (9912) |
+| WebSocket | `BARADB_PORT + 441` (9913) |
+
+Няма `BARADB_HTTP_PORT`.
+
+## Production Docker

 ```bash
-docker build -t baradb:latest .
-docker compose up -d
+export BARADB_JWT_SECRET="$(openssl rand -hex 32)"
+docker compose -f docker-compose.prod.yml up -d --build
 ```

-### Docker Compose файлове
+Auth е включен; без secret compose **спира**.

-| Файл | Назначение |
-|------|-----------|
-| `docker-compose.yml` | Development |
-| `docker-compose.prod.yml` | Production |
-| `docker-compose.override.yml` | Dev override (автоматично) |
-| `docker-compose.test.yml` | Тестова среда |
-
-### Production
+## Backup / restore drill

 ```bash
-docker compose -f docker-compose.prod.yml up -d
+./scripts/backup-restore-drill.sh
 ```

-### Docker Swarm
+## Health

 ```bash
-docker stack deploy -c docker-compose.prod.yml baradb
-```
-
-## systemd Услуга
-
-Създайте `/etc/systemd/system/baradb.service`:
-
-```ini
-[Unit]
-Description=BaraDB Multimodal Database
-After=network.target
-
-[Service]
-Type=simple
-User=baradb
-Group=baradb
-WorkingDirectory=/var/lib/baradb
-ExecStart=/usr/local/bin/baradadb
-Restart=always
-RestartSec=5
-
-Environment=BARADB_PORT=9472
-Environment=BARADB_HTTP_PORT=9470
-Environment=BARADB_DATA_DIR=/var/lib/baradb/data
-Environment=BARADB_LOG_LEVEL=info
-
-# Подсилване на сигурността
-NoNewPrivileges=true
-ProtectSystem=strict
-ProtectHome=true
-ReadWritePaths=/var/lib/baradb/data
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Активиране и стартиране:
-
-```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 systemctl daemon-reload
-sudo systemctl enable --now baradb
-```
-
-## Kubernetes
-
-### StatefulSet
-
-```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
-```
-
-## Reverse Proxy (nginx)
-
-```nginx
-upstream baradb_http {
-    server 127.0.0.1:9470;
-}
-
-upstream baradb_ws {
-    server 127.0.0.1:9471;
-}
-
-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/;
-        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;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-    }
-}
-```
-
-## Висока Достъпност (High Availability)
-
-### 3-Възел Raft Клъстер
-
-```bash
-# Възел 1
-BARADB_RAFT_NODE_ID=node1 \
-BARADB_RAFT_PEERS=node2:9001,node3:9001 \
-./build/baradadb
-
-# Възел 2
-BARADB_RAFT_NODE_ID=node2 \
-BARADB_RAFT_PEERS=node1:9001,node3:9001 \
-./build/baradadb
-
-# Възел 3
-BARADB_RAFT_NODE_ID=node3 \
-BARADB_RAFT_PEERS=node1:9001,node2:9001 \
-./build/baradadb
-```
-
-## Облачно Внедряване
-
-### AWS EC2
-
-Препоръчителна инстанция: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
-
-```bash
-# User data скрипт
-#!/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)
-
-```bash
-gcloud run deploy baradb \
-  --image gcr.io/PROJECT/baradb \
-  --port 9470 \
-  --memory 4Gi \
-  --cpu 2 \
-  --max-instances 10
+curl -s http://127.0.0.1:9912/health
 ```
@@ -0,0 +1,33 @@
+# Известни ограничения — v1.2.0 Production GA
+
+| Ниво | Значение |
+|------|----------|
+| **Supported (GA)** | Документирано, тествано, подходящо за prod в обхвата |
+| **Experimental** | Работи в тестове/demo; не е HA SLA |
+| **Not supported** | Извън обхват |
+
+## Матрица
+
+| Област | GA (v1.2.0) | Experimental / по-късно |
+|--------|-------------|-------------------------|
+| Single-node SQL + LSM | **Supported** | — |
+| Schema / FTS / HNSW / graphs persist | **Supported** | — |
+| Auth + JWT (когато е конфигуриран) | **Supported** | — |
+| Backup / restore | **Supported** | — |
+| Multi-DB (без Raft) | **Supported** | — |
+| Raft 3-node + SQL/DDL | **Experimental** | InstallSnapshot, membership |
+| Raft multi-DB | **Not supported** | само `default` |
+| Follower linearizable reads | **Not supported** | best-effort след apply |
+| ORC multi-thread shared LSM | **Not supported** | ARC по подразбиране |
+
+## GA (single-node)
+
+Crash recovery с WAL, schema/index persist, `/health` + `/metrics`, offline backup/restore.
+
+## Raft
+
+Виж [distributed.md](distributed.md). Staging/ops, **не** v1.2.0 HA продукт.
+
+## Виж също
+
+- [Deployment](deployment.md) · [Backup](backup.md) · [en limitations](../en/known-limitations.md)