Deploy the Server

The VectorFlow server is a Next.js application backed by PostgreSQL. This page covers deployment options, environment variables, persistent storage, and production hardening.

mkdir -p vectorflow && cd vectorflow

curl -sSfL -o docker-compose.yml \
  https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/docker/server/docker-compose.yml

cat > .env << 'EOF'
POSTGRES_PASSWORD=<random-32-char-string>
NEXTAUTH_SECRET=<random-32-char-string>
# NEXTAUTH_URL=https://vectorflow.example.com
EOF

docker compose up -d

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: vectorflow
      POSTGRES_USER: vectorflow
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vectorflow"]
    restart: unless-stopped

  vectorflow:
    image: ghcr.io/terrifiedbug/vectorflow-server:${VF_VERSION:-latest}
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://vectorflow:${POSTGRES_PASSWORD}@postgres:5432/vectorflow
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXTAUTH_URL: ${NEXTAUTH_URL}
    volumes:
      - vfdata:/app/.vectorflow
      - backups:/backups
    restart: unless-stopped

volumes:
  pgdata:
  vfdata:
  backups:

VF_VERSION=v0.3.0 docker compose up -d

# Uncomment in docker-compose.yml
ports:
  - "127.0.0.1:5432:5432"

curl -sSfL -o vectorflow.tar.gz \
  https://github.com/TerrifiedBug/vectorflow/releases/latest/download/vectorflow-server.tar.gz
mkdir -p /opt/vectorflow && tar xzf vectorflow.tar.gz -C /opt/vectorflow

CREATE USER vectorflow WITH PASSWORD 'your-strong-password';
CREATE DATABASE vectorflow OWNER vectorflow;

DATABASE_URL=postgresql://vectorflow:your-strong-password@localhost:5432/vectorflow
NEXTAUTH_SECRET=generate-a-random-32-char-string
NEXTAUTH_URL=https://vectorflow.example.com
PORT=3000
NODE_ENV=production

cd /opt/vectorflow
npx prisma migrate deploy

node server.js

# /etc/systemd/system/vectorflow.service
[Unit]
Description=VectorFlow Server
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=vectorflow
Group=vectorflow
WorkingDirectory=/opt/vectorflow
EnvironmentFile=/etc/vectorflow/server.env
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/vectorflow/.vectorflow /backups

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now vectorflow

Environment variables

When using the Docker Compose setup, the following variables go in your .env file and are interpolated into the Compose file:

Production considerations

Reverse proxy

In production, place VectorFlow behind a reverse proxy for TLS termination.

server {
    listen 443 ssl http2;
    server_name vectorflow.example.com;

    ssl_certificate     /etc/ssl/certs/vectorflow.crt;
    ssl_certificate_key /etc/ssl/private/vectorflow.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE streaming support (agent push channel)
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_cache off;
    }
}

vectorflow.example.com {
    reverse_proxy localhost:3000
}

When using a reverse proxy, set NEXTAUTH_URL to your public URL (e.g., https://vectorflow.example.com).

TLS

• Agents communicate with the server over HTTPS. Always terminate TLS in production.
• If you cannot use a reverse proxy, consider a TLS-terminating load balancer.

Database tuning

For deployments managing more than 50 agents, consider tuning PostgreSQL:

• Increase shared_buffers to 25% of available RAM
• Set work_mem to 64 MB
• Enable pg_stat_statements for query monitoring
• Schedule regular VACUUM ANALYZE runs

Resource requirements

These are minimums. The server is lightweight -- most resources go to PostgreSQL.

High Availability

VectorFlow supports running two or more instances behind a load balancer for high availability. When REDIS_URL is set, instances coordinate through Redis to provide:

• Leader election — only one instance runs singleton services (backup scheduler, alert evaluator, metric aggregation), with automatic failover if the leader goes down
• Cross-instance SSE broadcast — all SSE connections receive all fleet events regardless of which instance the client is connected to
• Metric distribution — heartbeat metrics processed by any instance are visible on all instances
• Agent push relay — configuration pushes reach agents connected to any instance

When REDIS_URL is not set, VectorFlow runs in single-instance mode with no behavioral change.

Prerequisites

• Redis 7+ (included in the HA Compose file)
• All instances must share the same DATABASE_URL, NEXTAUTH_SECRET, and REDIS_URL

Quick start

Download the HA Compose file and nginx config:

mkdir -p vectorflow && cd vectorflow

curl -sSfL -o docker-compose.ha.yml \
  https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/docker/server/docker-compose.ha.yml

curl -sSfL -o nginx-ha.conf \
  https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/docker/server/nginx-ha.conf

Create your .env file:

cat > .env << 'EOF'
POSTGRES_PASSWORD=<random-32-char-string>
NEXTAUTH_SECRET=<random-32-char-string>
NEXTAUTH_URL=http://localhost:3000
EOF

Start the stack:

docker compose -f docker-compose.ha.yml up -d

This starts five services: PostgreSQL, Redis, two VectorFlow instances (vf1 and vf2), and an nginx reverse proxy on port 3000.

How it works

On startup, instances compete for a Redis-based leader lock. The winner becomes the leader and runs singleton services (backup scheduler, alert evaluator, metric aggregation). The other instance runs as a follower, serving HTTP traffic and API requests but not running singletons. If the leader goes down, a follower automatically takes over.

Both instances sit behind nginx, which round-robins HTTP requests across them. SSE connections stay open to whichever instance the client connects to, and Redis pub/sub ensures all instances broadcast the same events.

Scaling beyond two instances

To add more instances, duplicate a vf service block in docker-compose.ha.yml and add the new service name to the nginx upstream block in nginx-ha.conf. Leader election and Redis coordination scale to any number of instances.