☁️ Deployment & Cloud Configuration¶

Production orchestration reference for deploying Spector across containerized, Kubernetes, and major public cloud infrastructures. Covers Docker volume layouts, Helm chart parameters, kernel sysctl tuning, and multi-cloud Terraform modules.

1. Docker Container Architecture¶

The official Spector Docker container (ghcr.io/spectrayan/spector:latest) uses a dual-tier runtime architecture:

flowchart LR
    subgraph Host["Host / Client"]
        ClientBrowser["Web Browser (UI)"]
        AgentClient["Agent / SDK Client"]
    end

    subgraph Container["Spector Container (ghcr.io/spectrayan/spector)"]
        direction TB
        Nginx["Nginx Reverse Proxy<br/>Port 8080"]
        Synapse["Spector Synapse Backend<br/>Port 7070 (Virtual Threads)"]
        Dashboard["Cortex Web Dashboard<br/>Static Angular SPA Assets"]
        VolumeData["/data Volume Mount<br/>(Panama FFM MMAP Storage)"]

        Nginx -->|/api/*| Synapse
        Nginx -->|/*| Dashboard
        Synapse --> VolumeData
    end

    ClientBrowser -->|HTTP 8080| Nginx
    AgentClient -->|HTTP 7070 or 8080/api| Nginx

Graceful Signal Draining¶

On docker stop or Kubernetes pod eviction (SIGTERM), entrypoint.sh traps the signal to guarantee zero data loss:

1. Nginx is ordered to quit (nginx -s quit), immediately closing external client ingress.
2. SIGTERM is forwarded to the Java PID, triggering Spector's internal JVM shutdown hook.
3. Spector finishes in-flight requests, flushes all dirty off-heap Panama memory pages (vectors.mmap), closes open WAL chunk files, and exits cleanly.

2. Docker Storage & Port Matrix¶

Network Ports¶

Filesystem Volumes¶

Docker Run Example¶

docker run -d \
  --name spector \
  -p 8080:8080 \
  -p 7070:7070 \
  -v spector-data:/data \
  -v $(pwd)/spector.yml:/app/spector.yml:ro \
  -e SPECTOR_EMBEDDING_PROVIDER=ollama \
  -e SPECTOR_EMBEDDING_BASE_URL=http://host.docker.internal:11434 \
  -e SPECTOR_EMBEDDING_MODEL=nomic-embed-text \
  -e SPECTOR_EMBEDDING_DIMS=768 \
  ghcr.io/spectrayan/spector:latest

3. Kubernetes & Helm Configuration Reference¶

The official Helm chart is located under deploy/helm/spector. Below is the complete reference table for all configurable parameters in values.yaml:

4. High-Performance StorageClasses for Vectors¶

Because Spector uses memory-mapped files (vectors.mmap) and synchronous WAL logging, selecting the correct StorageClass is critical for query latency and write throughput:

5. Terraform Cloud Modules Reference¶

Spector includes native Terraform modules under deploy/terraform/modules/ for automated infrastructure provisioning.

AWS ECS Fargate Module¶

Located at deploy/terraform/modules/aws-ecs:

Input Variables¶

Module Outputs¶

GCP Cloud Run Module¶

Located at deploy/terraform/modules/gcp-cloudrun:

Input Variables¶

Module Outputs¶

Azure Container Apps Module¶

Located at deploy/terraform/modules/azure-aca:

Input Variables¶

Module Outputs¶

6. Master Encryption Key Management & Fail-Closed Security¶

Spector uses AES-256-GCM envelope encryption with HKDF-SHA256 per-tenant key derivation for its universal credentials vault (credentials table, ADR-0076, Issue #1052).

Fail-Closed Production Invariant (SPE-SEC-002)¶

• Production Environments: When running in any profile outside dev and test (including the default production profile), SPECTOR_MASTER_ENCRYPTION_KEY (or spector.security.master-key) must be explicitly provided. If unset or blank, Spector refuses to boot and fails fast with taxonomy error [SPE-820-002 / SPE-SEC-002]:

  [SPE-820-002 / SPE-SEC-002] Master encryption key is required outside dev/test profiles (set SPECTOR_MASTER_ENCRYPTION_KEY or spector.security.master-key)
  

• Development Mode (dev profile): If unset, Spector falls back to a deterministic development key and prints a prominent WARN banner alerting developers that the configuration is insecure for production.

• Testing Mode (test profile): Falls back to a deterministic key with debug logging to allow automated test suites to execute without manual key management.

Key Generation¶

Generate a cryptographically secure 256-bit random key before deploying:

# 256-bit hexadecimal key (recommended)
openssl rand -hex 32

# Alternative: 256-bit Base64 key
openssl rand -base64 32

Key Injection Methods¶

1. Environment Variable:

   export SPECTOR_MASTER_ENCRYPTION_KEY="<64-hex-char-secret-key>"
   

2. Docker Secrets (Recommended for Swarm / Compose): Mount the secret at /run/secrets/spector_master_encryption_key. The container's entrypoint.sh automatically reads and exports it into the backend process.

3. Kubernetes Secret / Helm: Inject via secretRef.name or container environment variable in values.yaml:

   env:
     SPECTOR_MASTER_ENCRYPTION_KEY:
       valueFrom:
         secretKeyRef:
           name: spector-secrets
           key: master-encryption-key
   

Key Rotation Guidelines¶

1. Because the master key serves as the Key Encryption Key (KEK) for stored credentials, rotating it requires a phased re-encryption process:
   • Export or decrypt existing credentials using the current active key.
   • Deploy the new master key.
   • Re-encrypt and persist credentials under the new key.
2. In future BYOK releases (Phase 3 / ADR-0069), key derivation and rotation are delegated to customer-managed KMS endpoints (AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault Transit).