Deployment¶

This page covers deploying both the documentation site and the platform itself to OCI.

Deploying the documentation site¶

Build¶

cd /path/to/ent_ai_fabric_dev
python -m mkdocs build

Output is placed in site/ — a self-contained static website.

Option A: Local preview¶

python -m http.server 8000 --directory site

Open http://127.0.0.1:8000.

Option B: OCI Object Storage (recommended for teams)¶

# Upload to a public bucket
oci os object bulk-upload \
  --bucket-name docs-bucket \
  --src-dir site/ \
  --overwrite

# Enable static website hosting on the bucket in OCI Console
# Set index document: index.html

Option C: NGINX on OCI Compute¶

server {
    listen 80;
    server_name docs.your-domain.com;
    root /var/www/ent-ai-fabric/site;
    index index.html;
    location / { try_files $uri $uri/ =404; }
}

Option D: GitHub Pages¶

python -m mkdocs gh-deploy

Publishes to gh-pages branch automatically.

Deploying the platform to OCI¶

Step 1: Provision security infrastructure¶

cd inception_devops/security/terraform-get-db-token-function
terraform init && terraform apply

This creates the IAM token exchange function, policies, network, and logging needed for Token Factory and DB token flows.

Step 2: Build and push container images¶

cd inception_devops/containers
./build.sh mcp-sqlcl
./build.sh mcp-object-storage
./build.sh invoice-automation-backend
./push.sh <region>.ocir.io/<tenancy>/<repo>

Step 3: Deploy MCP servers¶

Each MCP server runs as an OCI Container Instance or OKE pod. Inject credentials via OCI Vault references — never plaintext in container config.

Example OCI CLI deployment:

oci container-instances container-instance create \
  --compartment-id $COMPARTMENT_ID \
  --display-name mcp-sqlcl \
  --containers '[{"imageUrl":"<region>.ocir.io/<tenancy>/mcp-sqlcl:latest"}]' \
  --shape CI.Standard.E4.Flex \
  --shape-config '{"ocpus":1,"memoryInGBs":4}'

Step 4: Configure API Gateway¶

In OCI Console → API Gateway → Deployments:

Route /mcp/ to the MCP server container private IP
Enable IDCS OAuth 2.0 authentication
Set Authorization: Bearer ${request.auth[access_token]} header transformation
Enable CORS for UI routes

See API Gateway Setup for full route and policy configuration.

Step 5: Deploy recipes¶

Invoice Automation:

cd inception_recipes/invoice_automation
npm run build
# Upload dist/ to OCI Object Storage or serve via NGINX

Smart Dispatch UI (production build):

cd inception_recipes/smart_dispatch/smart_dispatch_ui
npm run build
# dist/ contains the static build — serve via NGINX or OCI Object Storage
# Node.js gateway runs as a persistent process:
node server/index.js

Smart Dispatch agents (Python FastAPI):

cd inception_recipes/smart_dispatch/smart_dispatch_agents
uv run python -m src.api.dispatch_api
# or containerise and deploy to OCI Container Instances

Environment variables reference¶

All services are configured via environment variables. Use OCI Vault secrets for sensitive values in production.

MCP servers¶

Variable	Service	Description
`IDCS_DOMAIN`	All MCP servers	IDCS hostname — bare hostname only (no `https://`)
`IDCS_CLIENT_ID`	All MCP servers	OAuth client ID
`IDCS_CLIENT_SECRET`	All MCP servers	OAuth client secret — store in Vault
`SQLCL_PATH`	SQLcl MCP	Path to SQLcl binary
`SQLCL_CONNECTION`	SQLcl MCP	Saved wallet connection name
`ADB_DSN`	ADW MCP	Oracle ADB connection string
`ADB_WALLET_LOCATION`	ADW MCP	Path to wallet directory

OCI API key token exchange (non-interactive agents and CLI)¶

Variable	Service	Description
`OCI_IDENTITY_TOKEN_URL`	Agents, Node.js gateway	IDCS OAuth2 token endpoint
`OCI_IDENTITY_TENANCY_OCID`	Agents, Node.js gateway	OCI tenancy OCID
`OCI_IDENTITY_USER_OCID`	Agents, Node.js gateway	OCI user OCID
`OCI_IDENTITY_FINGERPRINT`	Agents, Node.js gateway	API key fingerprint
`OCI_IDENTITY_PRIVATE_KEY_FILE`	Agents, Node.js gateway	Path to RSA private key PEM
`OCI_IDENTITY_SCOPE`	Agents, Node.js gateway	OAuth scope — default `urn:opc:idm:__myscopes__`

Token Factory¶

Variable	Service	Description
`DOMAIN_URL`	Token Factory	Identity Domain base URL with port `443`
`DOMAIN_OCI_REGION`	Token Factory	OCI region for token exchange and Data Plane calls
`TOKEN_EXCHANGE_CREDS_OCID`	Token Factory	Vault secret OCID for `client_id:client_secret`
`TOKEN_FACTORY_ISSUER`	Token Factory	JWT `iss` claim — must match `IdentityPropagationTrust`
`TOKEN_FACTORY_PRIVATE_KEY_SECRET_OCID`	Token Factory	Vault secret OCID for RSA private key PEM
`TOKEN_FACTORY_CERT_SECRET_OCID`	Token Factory	Vault secret OCID for X.509 certificate PEM
`TOKEN_FACTORY_KID`	Token Factory	Identity Domain certificate store alias
`TOKEN_FACTORY_PROPAGATION_TRUST_CLAIM`	Token Factory	Extra JWT claim — format `name:value`

Agents and LLM¶

Variable	Service	Description
`OCI_GENAI_ENDPOINT`	Agents	OCI GenAI inference endpoint
`OCI_GENAI_MODEL_ID`	Agents	Model identifier
`OCI_EMBEDDING_MODEL`	Agents	Embedding model for vector memory
`OCI_COMPARTMENT_ID`	Agents	OCI compartment OCID
`LANGFUSE_SECRET_KEY`	Agents	LangFuse tracing key — store in Vault
`LANGFUSE_PUBLIC_KEY`	Agents	LangFuse public key
`LANGFUSE_BASE_URL`	Agents	LangFuse server URL

Smart Dispatch¶

Variable	Service	Description
`APP_BACKEND_PORT`	Node.js gateway	Express listen port — default `7002`
`DISPATCH_API_URL`	Node.js gateway	Python FastAPI URL — default `http://127.0.0.1:7001`
`MCP_URL`	Node.js gateway	SQLcl MCP endpoint — default `http://127.0.0.1:3001/mcp/`
`IAM_IDCS_CLIENT_ID`	Node.js gateway	IDCS client ID for web login OAuth2 flow
`IAM_IDCS_CLIENT_SECRET`	Node.js gateway	IDCS client secret — store in Vault
`IAM_IDCS_AUTHORIZE_URL`	Node.js gateway	IDCS `/oauth2/v1/authorize` endpoint
`IAM_IDCS_TOKEN_URL`	Node.js gateway	IDCS `/oauth2/v1/token` endpoint
`IAM_IDCS_REDIRECT_URI`	Node.js gateway	OAuth2 callback URL — `http://localhost:8000/callback`
`DISPATCH_API_HOST`	Python FastAPI	Bind host — default `127.0.0.1`
`DISPATCH_API_PORT`	Python FastAPI	Bind port — default `7001`
`MCP_SQLcl_URL`	Python agents	SQLcl MCP URL from agents side
`SQL_CL_CONNECTION`	Python agents	SQLcl connection name — default `SIDECARADB_HIGH`