# How to Deploy Semantica AGI to Production: Complete Docker Configuration Guide

> Deploy Semantica AGI to production using Docker. Configure FalkorDB and Semantica Explorer API with a private network and secure variables. Follow this complete guide for a seamless rollout.

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

---

**Deploy Semantica AGI to production by orchestrating two Docker containers—the FalkorDB graph database and the Semantica Explorer API—connected via a private bridge network with secure environment variables.**

Semantica AGI is an open-source Python framework for contextual AI that tracks decisions, provenance, and knowledge graphs using a polyglot graph store architecture. To deploy Semantica AGI to production, you run the FalkorDB labeled-property-graph database alongside the FastAPI-based Explorer service using the official Docker Compose configuration from the `semantica-agi/semantica` repository. This deployment pattern exposes HTTP endpoints for ingestion, reasoning, and decision-intelligence while maintaining a stateful graph backend.

## Production Architecture Overview

The production deployment consists of two primary services defined in [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml):

- **FalkorDB**: A native Labeled-Property-Graph (LPG) database that stores the Context Graph, temporal facts, decisions, and provenance data. It exposes port `6379` inside the private `semantica` network.
- **Semantica Explorer**: The HTTP API and interactive UI (also called the "MCP server") that handles knowledge graph construction, vector-store retrieval, SPARQL/Datalog queries, and decision recording. It exposes port `8000` to the host.

These containers communicate over a Docker bridge network named `semantica`, allowing the Explorer to reach FalkorDB at `falkordb:6379` via the `FALKORDB_HOST` and `FALKORDB_PORT` environment variables.

## Prerequisites and Initial Setup

Begin by cloning the repository and navigating to the project root:

```bash
git clone https://github.com/semantica-agi/semantica.git
cd semantica

```

The `Dockerfile` at the repository root builds the Explorer image from the latest Python package. Docker Compose handles the build automatically on first launch.

## Configuring Production Environment Variables

The Explorer reads critical runtime configuration from three environment variables defined in lines 7–15 of [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml):

- **`SEMANTICA_API_KEY`**: A secret token required for all protected endpoints. Generate a secure key using `openssl rand -hex 32`.
- **`SEMANTICA_ALLOW_ANONYMOUS`**: When set to `"true"`, API key checks are bypassed. Set this to `"false"` for production environments.
- **`ALLOWED_ORIGINS`**: The CORS whitelist for the UI. Defaults to `http://localhost:8000`; update this to include your production domain.

Store these variables in a `.env` file at the project root, which Docker Compose automatically loads:

```bash
export SEMANTICA_API_KEY=$(openssl rand -hex 32)
export SEMANTICA_ALLOW_ANONYMOUS=false
export ALLOWED_ORIGINS=https://your-domain.com

```

## Launching the Production Stack

Start the production deployment using the standard compose file. This creates the private `semantica` network and initializes both containers without source-code mounts:

```bash
docker compose up -d

```

For development environments requiring hot-reload and bundled UI tools, use the development variant instead:

```bash
docker compose -f docker-compose.dev.yml up -d

```

The development configuration mounts source code volumes for rapid iteration, while the production configuration runs immutable images.

## Verifying the Installation

Once containers are running, verify the deployment health using the built-in CLI diagnostic:

```bash
semantica doctor

```

This command runs a self-test of the Python package components. Successful execution ends with a "pass" status for all checks. The API is then reachable at `http://localhost:8000`, with the interactive UI served from the same address for graph exploration and provenance visualization.

## Production Client Integration

Connect your application code to the running server using the `ContextGraph` class from [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py). The client library discovers the API endpoint using the `SEMANTICA_API_KEY` environment variable:

```python
import os
from semantica.context import ContextGraph

os.environ["SEMANTICA_API_KEY"] = "your-generated-key"
graph = ContextGraph(advanced_analytics=True)

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature tooling, and team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

chain = graph.trace_decision_chain(decision_id)
print("Audit trail:", chain)

```

This snippet records a decision to the graph and retrieves its causal provenance chain, leveraging the unified graph store registry implemented in [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py).

## Swapping the Graph Backend (Optional)

Semantica supports multiple RDF and LPG backends including Neo4j, Blazegraph, and Apache Jena. To use a different graph store, replace the FalkorDB service in your [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml) and update the connection URI:

```yaml
services:
  neo4j:
    image: neo4j:5
    ports:
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/secure-password

```

Then configure the Explorer to connect via `NEO4J_URI=bolt://neo4j:7687` set as an environment variable. No Python code changes are required because [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py) abstracts all data access through a unified interface.

## Key Implementation Files

Understanding these source files helps troubleshoot production deployments:

- **[`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml)**: Defines the production container stack, environment variables, and network configuration.
- **[`docker-compose.dev.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.dev.yml)**: Development variant with hot-reload mounts and additional tooling.
- **[`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)**: The FastAPI-based HTTP server backing the Explorer UI and REST endpoints.
- **[`semantica/mcp/__main__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/__main__.py)**: Entry point invoked by `python -m semantica.mcp` used by the Docker image.
- **[`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py)**: High-level façade for recording decisions, querying graphs, and running reasoning pipelines.
- **[`semantica/visualization/visualization_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/visualization_provenance.py)**: Powers the interactive provenance graphs and decision visualizations in the UI.
- **[`semantica/utils/logging.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/logging.py)**: Centralized logging configuration for both production and development containers.

## Summary

Deploying Semantica AGI to production requires orchestrating two containerized services with specific security configurations:

- Run **FalkorDB** and the **Semantica Explorer** via [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml) on a private bridge network
- Configure `SEMANTICA_API_KEY` and disable anonymous access for production security
- Verify deployment health using the `semantica doctor` CLI command
- Connect applications using the `ContextGraph` client from [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py)
- Swap graph backends by updating the Docker Compose service and connection URI without modifying Python code

## Frequently Asked Questions

### Is Semantica AGI suitable for enterprise production workloads?

Yes, the architecture is designed for production use through containerized isolation and configurable security. The separation of concerns between the graph database (FalkorDB) and the API layer (Explorer) allows independent scaling, while the environment variable configuration in [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml) supports enterprise security requirements like API key management and CORS restrictions.

### Can I deploy Semantica AGI without Docker?

While Docker is the officially supported deployment method defined in the repository, you can run the components manually by installing the Python package and connecting to a compatible graph store. You must manually configure the `FALKORDB_HOST` and `FALKORDB_PORT` variables to point to your database instance, and launch the FastAPI server using `python -m semantica.mcp` as defined in [`semantica/mcp/__main__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/__main__.py).

### How do I migrate from the default FalkorDB to Neo4j?

Migration requires only Docker Compose changes. Replace the `falkordb` service with an official Neo4j image, update the connection URI environment variable in the Explorer service configuration, and restart the stack. The Python codebase requires no changes because the graph store registry in [`semantica/graph_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/registry.py) handles all backend-specific logic transparently.

### What is the difference between production and development deployment modes?

Production mode uses [`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.yml) with immutable container images and no volume mounts, optimizing for stability and security. Development mode uses [`docker-compose.dev.yml`](https://github.com/semantica-agi/semantica/blob/main/docker-compose.dev.yml) which mounts source code directories for hot-reload, includes additional debugging tools, and may enable anonymous API access for rapid iteration. Never use development configuration for production deployments.