Self-hosting overview

Understand the supported deployment topology, prerequisites, health boundaries, and recovery model.

Organizational AI Memory is self-hosted as independently deployable API, worker, MCP, web, and documentation services around PostgreSQL, OpenFGA, Keycloak, and object storage. The repository contains a production-shaped Compose and delivery path, but deploying it does not by itself certify pilot readiness.

Deployment boundary

Edge

DNS, TLS, security headers, and reverse-proxy routes.

Applications

Web, API, worker, MCP, and docs run as separate containers.

Governance

Keycloak authenticates and OpenFGA resolves relationship authorization.

Persistence

PostgreSQL and object storage retain canonical state and evidence.

A reverse proxy terminates public traffic. Product services share canonical dependencies; the documentation container remains independent.

Local infrastructure

For development, compose.yaml starts PostgreSQL 18 with pgvector and Apache AGE, OpenFGA with its own database, Keycloak, and MinIO. Product applications run from Gradle or pnpm. The documentation container is an opt-in Compose profile and does not start product dependencies.

docker compose up -d
.\scripts\bootstrap-openfga.ps1
docker compose --profile docs up --build docs

The docs health endpoint is http://localhost:3000/healthz. Product startup and the complete demo flow are covered in the Quickstart.

Production responsibilities

Boundary	Responsibility
Reverse proxy	TLS termination, public routing, security headers, compression, and caching policy
API	Interactive delivery, OIDC BFF and bearer chains, Flyway migration ownership, canonical writes
Worker	Leased connector, ingestion, authorization-projection, and graph-index work
MCP	Stateless protected resource and short-lived token exchange
Web	Static product client served behind the same trusted origin boundary
Docs	Independent standalone Next.js container; failure does not affect the product
PostgreSQL/object storage	Persistent canonical state and immutable evidence bytes

API runs the schema migration. Worker and MCP validate the existing schema and must not race Flyway.

Configuration and secrets

Production uses the prod profile and requires explicit database, OIDC, OpenFGA, object-storage, and AI settings. Known local credentials, invalid public origins, and unsafe identity/AI routes abort startup.

Store values in the deployment platform's managed environment or secret store. Commit only the example contract. Provider keys stay server-side; browser code must never receive them. The product has no offline or permit-all profile.

Persistence and recovery

Back up PostgreSQL and immutable object storage as one recovery unit. Search, vector, graph, and external authorization projections are rebuildable, but their publication coordinates and source evidence live in the canonical ledger.

Use immutable image references. Before mutation, record the current image set; after startup, require container health plus public OIDC, API, web, and MCP smokes. A failed rollout must restore the previous image references and recreate only the affected services.

The docs service has its own image, deployment lock, health check, and rollback path so a documentation release cannot restart product services.

Security headers and network exposure

Expose only the reverse proxy. Keep PostgreSQL, OpenFGA internals, object storage, API-to-worker dependencies, and container ports on private networks. Enable HSTS only after HTTPS and login/logout are verified. Apply nosniff, framing denial, a strict referrer policy, and a restrictive permissions policy.