Skip to main content

Source: docs/manual/debian-deploy.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Debian Deployment Guide

This guide documents a full single-node Debian deployment for Cruvero services. It includes PostgreSQL, Dragonfly, Qdrant, NATS JetStream, optional self-hosted Temporal, and systemd units for Cruvero binaries.

Source: cmd/*, internal/config/config.go, charts/cruvero/values-dev.yaml

Scope​

  • Target: Debian 12+ on x86_64
  • Topology: single host, production-hardened baseline
  • Runtime services:
    • PostgreSQL (primary relational store)
    • Dragonfly (cache/quota/episodic memory)
    • Qdrant (vector store)
    • NATS JetStream (events/discovery)
    • Temporal (optional self-hosted; external Temporal is also supported)
    • Cruvero services (worker, api, ui, optional graph-worker, embed-worker)

Host Prerequisites​

sudo apt-get update
sudo apt-get install -y \
  ca-certificates curl gnupg lsb-release jq \
  postgresql postgresql-contrib redis-tools

Install Docker (recommended for Qdrant + optional Temporal):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"

PostgreSQL​

sudo systemctl enable --now postgresql
sudo -u postgres psql <<'SQL'
CREATE USER cruvero WITH PASSWORD 'replace-me';
CREATE DATABASE cruvero OWNER cruvero;
\c cruvero
CREATE EXTENSION IF NOT EXISTS vector;
SQL

Connection string example:

export CRUVERO_POSTGRES_URL='postgres://cruvero:[email protected]:5432/cruvero?sslmode=disable'

Dragonfly​

Use the official container image:

docker run -d --name dragonfly \
  --restart unless-stopped \
  -p 6379:6379 \
  docker.dragonflydb.io/dragonflydb/dragonfly:latest \
  --maxmemory=1gb

Runtime env:

CRUVERO_DRAGONFLY_ADDR=127.0.0.1:6379
CRUVERO_QUOTA_STORE=dragonfly
CRUVERO_MEMORY_EPISODIC_STORE=redis

Qdrant​

docker volume create qdrant_data
docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant:latest

Runtime env:

CRUVERO_VECTOR_STORE=qdrant
CRUVERO_QDRANT_URL=http://127.0.0.1:6334

NATS JetStream​

curl -L https://github.com/nats-io/nats-server/releases/download/v2.10.x/nats-server-v2.10.x-linux-amd64.tar.gz | tar xz
sudo cp nats-server-v2.10.x-linux-amd64/nats-server /usr/local/bin/
sudo useradd --system --home /var/lib/nats --shell /usr/sbin/nologin nats || true
sudo mkdir -p /var/lib/nats
sudo chown -R nats:nats /var/lib/nats

Create /etc/systemd/system/nats.service:

[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
User=nats
ExecStart=/usr/local/bin/nats-server --jetstream --store_dir /var/lib/nats --max_mem 256M -m 8222
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now nats

Runtime env:

CRUVERO_EVENTS_BACKEND=nats
CRUVERO_NATS_URL=nats://127.0.0.1:4222
CRUVERO_EVENTS_SUBJECT_PREFIX=cruvero
CRUVERO_AUDIT_BUFFER=nats

Temporal (Optional Self-Hosted)​

If you do not already use managed/external Temporal:

docker run -d --name temporal \
  --restart unless-stopped \
  -p 7233:7233 \
  temporalio/auto-setup:1.27

Runtime env:

CRUVERO_TEMPORAL_ADDRESS=127.0.0.1:7233
CRUVERO_TEMPORAL_NAMESPACE=default
CRUVERO_TEMPORAL_TLS=false

Cruvero Environment File​

Create /etc/cruvero/cruvero.env:

CRUVERO_LOG_LEVEL=info
CRUVERO_POSTGRES_URL=postgres://cruvero:[email protected]:5432/cruvero?sslmode=disable
CRUVERO_DRAGONFLY_ADDR=127.0.0.1:6379
CRUVERO_NATS_URL=nats://127.0.0.1:4222
CRUVERO_EVENTS_BACKEND=nats
CRUVERO_EVENTS_SUBJECT_PREFIX=cruvero
CRUVERO_AUDIT_BUFFER=nats
CRUVERO_VECTOR_STORE=qdrant
CRUVERO_QDRANT_URL=http://127.0.0.1:6334
CRUVERO_TEMPORAL_ADDRESS=127.0.0.1:7233
CRUVERO_TEMPORAL_NAMESPACE=default
CRUVERO_TEMPORAL_TLS=false
CRUVERO_EMBEDDING_PROVIDER=openai
CRUVERO_EMBEDDING_MODEL=text-embedding-3-small
CRUVERO_OPENAI_API_KEY=replace-me
CRUVERO_OPENAI_CHAT_API_KEY=replace-me
CRUVERO_UI_AUTH=none

Systemd Units (Cruvero Services)​

Assume binaries are installed under /opt/cruvero/bin.

cruvero-worker.service​

[Unit]
Description=Cruvero Worker
After=network-online.target postgresql.service nats.service

[Service]
Type=simple
User=cruvero
WorkingDirectory=/opt/cruvero
EnvironmentFile=/etc/cruvero/cruvero.env
ExecStart=/opt/cruvero/bin/worker
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

cruvero-api.service​

[Unit]
Description=Cruvero API
After=network-online.target

[Service]
Type=simple
User=cruvero
WorkingDirectory=/opt/cruvero
EnvironmentFile=/etc/cruvero/cruvero.env
ExecStart=/opt/cruvero/bin/api --port 8900
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

cruvero-ui.service​

[Unit]
Description=Cruvero UI
After=network-online.target

[Service]
Type=simple
User=cruvero
WorkingDirectory=/opt/cruvero
EnvironmentFile=/etc/cruvero/cruvero.env
ExecStart=/opt/cruvero/bin/ui --addr :8080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Optional: cruvero-embed-worker.service​

[Unit]
Description=Cruvero Embed Worker
After=network-online.target nats.service postgresql.service

[Service]
Type=simple
User=cruvero
WorkingDirectory=/opt/cruvero
EnvironmentFile=/etc/cruvero/cruvero.env
ExecStart=/opt/cruvero/bin/embed-worker
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Optional: cruvero-graph-worker.service​

[Unit]
Description=Cruvero Graph Worker
After=network-online.target

[Service]
Type=simple
User=cruvero
WorkingDirectory=/opt/cruvero
EnvironmentFile=/etc/cruvero/cruvero.env
ExecStart=/opt/cruvero/bin/graph-worker
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Enable services:

sudo systemctl daemon-reload
sudo systemctl enable --now cruvero-worker cruvero-api cruvero-ui
# Optional:
sudo systemctl enable --now cruvero-embed-worker cruvero-graph-worker

TLS and Reverse Proxy​

Place API/UI behind Caddy, Nginx, or Traefik. Example Caddy snippet:

cruvero.example.com {
  reverse_proxy 127.0.0.1:8080
}

cruvero-api.example.com {
  reverse_proxy 127.0.0.1:8900
}

If NATS TLS is enabled, set:

CRUVERO_NATS_TLS=auto
CRUVERO_NATS_CREDS_FILE=/etc/cruvero/nats.creds

Validation Checklist​

# Core services
systemctl status postgresql nats cruvero-worker cruvero-api cruvero-ui

# Runtime health
curl -fsS http://127.0.0.1:8080/api/health | jq .
curl -fsS http://127.0.0.1:8900/v1/health | jq .

# Event bus health
go run ./cmd/event-bus --nats-url nats://127.0.0.1:4222 status

# End-to-end smoke
go run ./cmd/run --prompt "Fetch https://example.com and return status code" --max-steps 4

Notes​

  • This Debian guide is for direct host deployment. For GitOps/containerized deployment, use kubernetes-deployment.md.
  • If you already run managed Temporal/Postgres/NATS, keep only Cruvero binaries and point env vars to those managed endpoints.