Skip to content
ContextUnity

Infrastructure Services

ContextUnity relies on several external infrastructure services to manage state, orchestrate background tasks, and secure application secrets.

This document outlines how these services are configured for local development versus production deployments via Ansible.

1. Redis (Service Mesh Registry)

Redis serves as the centralized, high-performance state store for Service Discovery and Project Ownership.

Development Setups

In standard development mode, Redis is completely optional. If redis is not installed or the server is unavailable, ContextCore fails open gracefully, allowing you to test LLM scripts locally without Docker. If you do want Redis locally, a standard unencrypted container works fine:

Terminal window
export REDIS_URL="redis://localhost:6379/0"

Production Setup (Ansible)

In production, Redis is mandatory to enforce Zero-Trust anti-spoofing. Our Ansible playbooks (infrastructure/ansible/roles/cu_service/templates/*.env.j2) inject REDIS_URL automatically.

TLS Requirement: If your Redis is hosted on a managed cloud (e.g. AWS ElastiCache) or cross-VPC, you should explicitly set the redis_url variable in your Ansible inventory to use the secure scheme:

# In your host_vars/prod.yml
redis_url: "rediss://default:SecurePassword123!@redis.internal.vpc:6379/0"

ContextCore’s Pydantic config explicitly validates rediss:// and will establish a cryptographically secure TLS tunnel.

2. PostgreSQL (Memory & Commerce)

PostgreSQL is the heavy lifter. It powers both the ContextBrain (Semantic Memory) and ContextCommerce (PIM), utilizing the pgvector extension for embeddings and ltree for taxonomies.

Development Setups

Locally, developers use docker-compose to spin up a single Postgres instance:

Terminal window
export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/brain"
export SYNC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/brain"

Production Setup

Production environments run on heavily tuned instances (e.g. Google Cloud SQL or AWS RDS).

Requirements for Prod:

  • pgvector: Must be explicitly installed on the cloud provider.
  • Connection Pooling: Use PgBouncer to manage high volumes of concurrent gRPC requests, as every incoming ContextUnit stream can request multiple vector lookups.
  • Role-Level Security (RLS): The brain_app role used by the services must not have SUPERUSER or BYPASSRLS privileges. RLS is strictly enforced at the kernel level for Tenant Isolation.

3. Temporal (Background Execution)

ContextWorker relies purely on HashiCorp / Temporal.io for durable workflow execution (e.g., scraping 100k products).

Development Setups

For local dev, you can use the Temporal CLI to spin up an ephemeral cluster in memory:

Terminal window
temporal server start-dev
export TEMPORAL_URL="localhost:7233"
export TEMPORAL_NAMESPACE="default"

Production Setup

In production, Temporal requires its own isolated cluster (usually backed by Cassandra or PostgreSQL).

Ansible deployment automatically configures workers with:

# In your Ansible configuration
temporal_host: "temporal-frontend.internal.vpc:7233"
temporal_namespace: "contextunity_prod"

Because Temporal traffic contains plain-text workflow arguments, mTLS (Mutual TLS) must be enabled between the ContextWorker pods and the Temporal Frontend in production.

4. Shield Secrets Vault

Rather than baking API keys into agent code, ContextShield provides secure Secrets retrieval via its Vault gRPC API. The storage layer underneath Shield is swappable based on environment.

1. EnvSecretStore (Dev / Open-Source)

The default. It statically loads secrets into Shield’s memory exclusively from the environment.

Terminal window
# Prefix variables with SHIELD_SECRET_
export SHIELD_SECRET_OPENAI_API_KEY="sk-proj-123"

Best for: Local testing or small single-tenant VM setups.

2. PgSecretStore (Enterprise)

Stores secrets inside the primary PostgreSQL database, but encrypts them “at-rest” using a master key (e.g., from Cloud KMS or a secure env variable). Best for: Multi-tenant platforms where dynamically adding new API keys is required (via the admin dashboard), without restarting the service.

3. VaultSecretStore (Enterprise)

Integrates directly with HashiCorp Vault. Shield queries Vault over mTLS. Best for: Huge enterprises where Security Ops centrally controls secret rotation independent of the ContextUnity app.