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

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:

• 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:

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:

• 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:

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:

docker compose up -d

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

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:

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. The client library discovers the API endpoint using the SEMANTICA_API_KEY environment variable:

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.

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 and update the connection URI:

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 abstracts all data access through a unified interface.

Key Implementation Files

Understanding these source files helps troubleshoot production deployments:

• docker-compose.yml: Defines the production container stack, environment variables, and network configuration.
• docker-compose.dev.yml: Development variant with hot-reload mounts and additional tooling.
• semantica/mcp/server.py: The FastAPI-based HTTP server backing the Explorer UI and REST endpoints.
• semantica/mcp/__main__.py: Entry point invoked by python -m semantica.mcp used by the Docker image.
• semantica/context.py: High-level façade for recording decisions, querying graphs, and running reasoning pipelines.
• semantica/visualization/visualization_provenance.py: Powers the interactive provenance graphs and decision visualizations in the UI.
• 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 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
• 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 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.

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 handles all backend-specific logic transparently.

What is the difference between production and development deployment modes?

Production mode uses docker-compose.yml with immutable container images and no volume mounts, optimizing for stability and security. Development mode uses 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}