# How to Deploy Semantica to a Production Environment: Complete Platform Guide

> Deploy Semantica to production with this comprehensive guide. Learn to provision stores, configure environment variables, and apply platform manifests for successful deployment.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Deploying Semantica to production involves provisioning durable graph and vector stores, configuring environment variables like `SEMANTICA_SECRET_KEY` and `SEMANTICA_API_KEY`, and applying the appropriate platform manifest (Docker, Kubernetes, Helm, Render, Fly.io, or cloud-native services).**

Semantica is a modular, polyglot graph-native platform for building context-aware AI systems. Whether you're running a single-node Docker deployment or scaling to a multi-region Kubernetes cluster, the same core architecture applies: a **knowledge-graph engine**, **decision-intelligence layer**, and **pluggable vector-store adapters**. This guide covers every production deployment pattern available in the [semantica-agi/semantica](https://github.com/semantica-agi/semantica) repository.

## Production Deployment Patterns Overview

Choose your deployment target based on operational requirements:

| Pattern | Best For | Key Files |
|---------|----------|-----------|
| **Docker** | Quick self-hosted rollout | `Dockerfile` |
| **Kubernetes / Helm** | High-availability, scalable clusters | `deploy/kubernetes/`, `deploy/helm/` |
| **Render** | Managed SaaS-style hosting | [`deploy/render/render.yaml`](https://github.com/semantica-agi/semantica/blob/main/deploy/render/render.yaml) |
| **Fly.io** | Low-latency global edge deployment | [`deploy/fly/fly.toml`](https://github.com/semantica-agi/semantica/blob/main/deploy/fly/fly.toml) |
| **Google Cloud / Azure** | Enterprise cloud-native environments | Cloud-specific manifests |
| **On-prem / Private cloud** | Strict data sovereignty | Raw Kubernetes manifests |

All patterns share the same runtime: the **MCP Server** ([`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)) exposes the graph over REST, while [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py) provides the `ContextGraph` implementation and [`semantica/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store.py) handles vector-store abstraction.

## Kubernetes Production Deployment

Kubernetes is the recommended path for production workloads requiring scalability and rollout control.

### Step 1: Configure Secrets

Create your secrets file from the provided template:

```bash
cp deploy/kubernetes/secret.yaml.example deploy/kubernetes/secret.yaml

# Edit secret.yaml to set:

# - SEMANTICA_SECRET_KEY (32+ byte random hex)

# - DATABASE_URL (persistent graph store)

# - VECTOR_STORE_URL (Qdrant, Pinecone, etc.)

```

The [`secret.yaml`](https://github.com/semantica-agi/semantica/blob/main/secret.yaml) file is intentionally excluded from [`kustomization.yaml`](https://github.com/semantica-agi/semantica/blob/main/kustomization.yaml) to prevent credential leakage. See [deploy/kubernetes/README.md](https://github.com/semantica-agi/semantica/blob/main/deploy/kubernetes/README.md) for details.

### Step 2: Update Image and Ingress

Modify [`deploy/kubernetes/kustomization.yaml`](https://github.com/semantica-agi/semantica/blob/main/deploy/kubernetes/kustomization.yaml):
- Replace the placeholder image digest with `semantica/semantica:<version>`
- Set the Ingress `host` to your public domain (e.g., `semantica.mycompany.com`)

### Step 3: Apply Manifests

```bash
kubectl apply -f deploy/kubernetes/secret.yaml
kubectl apply -k deploy/kubernetes
kubectl -n semantica rollout status deployment/knowledge-explorer

```

### Step 4: Verify Deployment

```bash
curl -H "X-API-Key: $SEMANTICA_API_KEY" https://semantica.mycompany.com/health
semantica doctor

```

A passing health check confirms the graph, vector store, and MCP server are reachable.

## Helm Deployment for Production Upgrades

For teams preferring declarative Helm management, the chart at `deploy/helm/knowledge-explorer` supports production values overlays:

```bash
helm upgrade --install knowledge-explorer deploy/helm/knowledge-explorer \
  --namespace semantica --create-namespace \
  -f deploy/helm/knowledge-explorer/values.prod.yaml

```

Reference [deploy/helm/README.md](https://github.com/semantica-agi/semantica/blob/main/deploy/helm/README.md) for available values.

## Managed Platform Deployments

### Render Deployment

Render provides automatic `API_KEY` generation and public URL exposure. Run:

```bash
render blueprints validate deploy/render/render.yaml
render blueprint apply deploy/render/render.yaml

```

Render automatically injects `SEMANTICA_API_KEY` into your environment. See [deploy/render/README.md](https://github.com/semantica-agi/semantica/blob/main/deploy/render/README.md).

### Fly.io Deployment

For edge-aware global deployment with automatic TLS:

```bash
flyctl launch --copy-config --config deploy/fly/fly.toml --no-deploy
flyctl deploy --config deploy/fly/fly.toml

```

Protected routes require the `X-API-Key` header. Details in [deploy/fly/README.md](https://github.com/semantica-agi/semantica/blob/main/deploy/fly/README.md).

### Docker Single-Node Production

For self-contained hosting without orchestration:

```bash
docker pull semantica/semantica:latest
docker run -d \
  -p 8000:8000 \
  -e SEMANTICA_SECRET_KEY=$(openssl rand -hex 32) \
  -e VECTOR_BACKEND=qdrant \
  -e VECTOR_URL=https://qdrant.mycompany.com \
  semantica/semantica

```

## Configuring Production Data Stores

Production workloads require durable backends. Configure via environment variables:

**Graph Stores (LPG/RDF)**
- Neo4j, FalkorDB, Apache AGE, AWS Neptune → `GRAPH_BACKEND_URL`
- Blazegraph, Apache Jena, Oxigraph → RDF store endpoints

**Vector Stores**
- Qdrant, Pinecone, Weaviate, Milvus, PgVector → `QDRANT_URL`, `PINECONE_API_KEY`, etc.

Update these before starting the service—data written to in-memory backends will not persist across restarts.

## Monitoring and Observability

Semantica emits structured logs to stdout for aggregation into Loki, Datadog, or similar systems. For metrics:

- Scrape the `/metrics` endpoint with Prometheus
- Configure alerting on graph store connection failures and vector store latency

## Production Code Examples

### Connect to Hosted Vector Store

```python
from semantica.context import ContextGraph
from semantica.vector_store import VectorStore

# Production Qdrant instance

vs = VectorStore(
    backend="qdrant",
    url="https://qdrant.mycompany.com",
    api_key=os.getenv("QDRANT_API_KEY")
)
graph = ContextGraph(advanced_analytics=True, vector_store=vs)

# Persisted decision with full provenance

decision_id = graph.record_decision(
    category="risk_assessment",
    scenario="Transaction flagged for review",
    reasoning="Velocity pattern matches known fraud",
    outcome="manual_review",
    confidence=0.87
)

```

### Query Production API from Client Service

```python
import requests

API_URL = "https://semantica.mycompany.com/api"
API_KEY = os.getenv("SEMANTICA_API_KEY")

def audit_decision(decision_id: str) -> dict:
    resp = requests.get(
        f"{API_URL}/decisions/{decision_id}/trace",
        headers={"X-API-Key": API_KEY}
    )
    resp.raise_for_status()
    return resp.json()

audit = audit_decision(decision_id)

```

## Key Production Files Reference

| File | Purpose |
|------|---------|
| `Dockerfile` | Production container build |
| `deploy/kubernetes/secret.yaml.example` | Secrets template |
| [`deploy/kubernetes/README.md`](https://github.com/semantica-agi/semantica/blob/main/deploy/kubernetes/README.md) | K8s deployment guide |
| `deploy/helm/knowledge-explorer/` | Helm chart |
| [`deploy/render/render.yaml`](https://github.com/semantica-agi/semantica/blob/main/deploy/render/render.yaml) | Render blueprint |
| [`deploy/fly/fly.toml`](https://github.com/semantica-agi/semantica/blob/main/deploy/fly/fly.toml) | Fly.io configuration |
| [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) | REST API implementation |
| [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py) | `ContextGraph` core |
| [`semantica/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store.py) | Vector store abstraction |

## Summary

Deploying Semantica to production follows a consistent pattern across platforms:

- **Provision durable stores** for graph and vector data
- **Secure secrets** (`SEMANTICA_SECRET_KEY`, `SEMANTICA_API_KEY`) outside version control
- **Apply platform manifests** (Kubernetes, Helm, Docker, Render, or Fly.io)
- **Verify health** before accepting traffic
- **Enable monitoring** via structured logs and Prometheus metrics

The modular `ContextGraph` and `VectorStore` abstractions in [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py) and [`semantica/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store.py) ensure backend swaps require no code changes.

## Frequently Asked Questions

### What environment variables are required for semantica production deployment?

Minimum required variables are `SEMANTICA_SECRET_KEY` (32+ byte random hex for session/cookie signing) and `SEMANTICA_API_KEY` (for API authentication). Additionally, configure backend-specific variables: `DATABASE_URL` or `GRAPH_BACKEND_URL` for the graph store, and `QDRANT_URL`, `PINECONE_API_KEY`, or equivalent for your chosen vector store.

### Can semantica run without Kubernetes?

Yes. **Docker** supports single-node production deployments. **Render** and **Fly.io** provide managed alternatives with minimal configuration. The same container image (`semantica/semantica`) powers all deployment patterns, and the MCP server ([`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)) functions identically regardless of orchestration layer.

### How do I migrate between vector stores in production?

Use the `VectorStore` abstraction in [`semantica/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store.py). Instantiate the source and target backends, export embeddings via the store's native tools, then update `VECTOR_BACKEND` and `VECTOR_URL` environment variables. No application code changes are required because `ContextGraph` accepts any `VectorStore` implementation.

### Is there a health check endpoint for load balancer configuration?

Yes. The MCP server exposes `/health` which validates connectivity to the graph store, vector store, and internal services. Configure your load balancer or ingress to hit this endpoint—successful responses indicate the deployment is ready for traffic.