Purple8 Hyper Graph — Developer Deployment & Integration Patterns (Fly, AWS & OpenShift)

Scope. This guide is the developer-facing path: deploy a Purple8 Hyper Graph (v0.72.0) instance, then wire your application and your AI agents to it on Fly.io, AWS, and Red Hat OpenShift. For deep, platform-by-platform infra tuning (volumes, RAM sizing, per-platform gotchas across Railway/Hetzner/Render/GCP too), see CLOUD_DEPLOYMENT_GUIDE.md. For MCP client setup, see MCP_CLIENTS.md.

Purple8 is a single in-process backend — graph (BrickCoreStorage / Cortex) + vector (HNSW) + document + full-text + workflow (JourneyEngine) + auth/RBAC + 125 MCP tools across 16 namespaces, one container, one port (8000 in Docker, 8100 when running python -m purple8_graph.secure_server locally). There is no separate database, vector store, workflow engine, or auth service to deploy. That is the whole point: one artifact to run, two entry points to integrate (REST/SDK for apps, MCP for agents).

0. The integration model in one picture

                         ┌──────────────────────────────────────────────────┐
   Your app frontend ───▶│  Purple8 Hyper Graph v0.72.0 (port 8000 / 8100)  │
   (React/Next/…)        │  ├─ /ingest  /rag  /graph  /journey  /lcnc       │
                         │  ├─ /auth    (JWT + API keys, 4-tier RBAC)       │
   AI agents  ──────────▶│  └─ /mcp/sse (125 MCP tools · 16 namespaces)     │
   (Claude/VSCode/…)     │                                                  │
                         │  GraphEngine (BrickCoreStorage + BrickWAL +      │
                         │  CortexAutoConfig) + HNSW + Journey + KMS + SOC  │
                         └───────────────┬──────────────────────────────────┘
                                         │  (optional sidecar)
   Documents ───────────────────────────▶  Purple8 DocIntel v0.12.5 (:8200)
   (70+ formats · 75+ languages)           parse → extract → POST /ingest

Everything below is about standing up that box on Fly, AWS, or OpenShift, then pointing your app and agents at it.

1. Prerequisites & Self-Hosted Licensing (2 Tiers)

Container images:
- Developer (Self-Hosted Free — $0): ghcr.io/purple8-technologies/purple8-graph:developer (or :0.72.0) — up to 50K nodes, 1 MCP agent, full engine for local development, prototyping, and evaluation.
- Enterprise / Custom (Self-Hosted): Unlock unlimited nodes & MCP agents, SSO/OIDC/SAML, 4-tier RBAC, immutable audit trail, managed KMS (Vault · AWS · GCP · Azure), Raft HA & failover, horizontal sharding, Supergraph federation, and SOC vertical by supplying PURPLE8_LICENSE_JWT (PURPLE8_REQUIRE_LICENSE=1). Also available as a Red Hat UBI9 / OpenShift-certified image (Dockerfile.rhel, arbitrary-UID group 0 ready).
A persistent volume. Purple8 is stateful (BrickWAL + BrickCoreStorage + HNSW index). Never run it on an ephemeral filesystem — you will lose data on redeploy.

Secrets to set (minimum):

Env var	Purpose
`P8G_API_KEY` or admin bootstrap creds	first admin / API auth
`P8G_JWT_SECRET`	signs user JWTs — strong random value (min 32 chars)
`P8G_CORS_ORIGINS`	comma-separated allow-list for your frontend origin(s)
`PURPLE8_REQUIRE_LICENSE=1`	fail closed if the license is missing (Enterprise production)
`KMS_PROVIDER` (+ `KMS_KEY_ID`)	AES-256-GCM at-rest encryption (`KMS_GUIDE.md`)

The data path defaults to ./data inside the container — you must set P8G_DATA_PATH to the mounted volume (e.g. /data) or state is lost on redeploy.

2. Fly.io — recommended for cloud

Fly gives deterministic RAM sizing, fly secrets set without a redeploy, and Fly Volumes that persist across deploys. This is the fastest path to a public HTTPS instance (which Claude Web and other remote agents require).

2.1 Deploy

bash

fly launch --no-deploy --name my-purple8      # generates fly.toml
fly volumes create p8g_data --size 10 --region iad

fly.toml:

toml

app = "my-purple8"
primary_region = "iad"

[build]
  image = "ghcr.io/purple8-technologies/purple8-graph:0.72.0"

[env]
  P8G_PORT = "8000"
  P8G_DATA_PATH = "/data"
  P8G_CORS_ORIGINS = "https://app.yourco.com"
  PURPLE8_REQUIRE_LICENSE = "1"

[[mounts]]
  source = "p8g_data"
  destination = "/data"

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = false
  min_machines_running = 1        # keep BrickWAL & HNSW warm; avoid cold starts
  [http_service.concurrency]
    type = "requests"
    hard_limit = 250
    soft_limit = 200

[[vm]]
  memory = "2gb"                  # bounded RSS via CortexAutoConfig; see note below
  cpu_kind = "shared"
  cpus = 2

Set secrets (take effect immediately, no redeploy):

bash

fly secrets set \
  P8G_JWT_SECRET="$(openssl rand -hex 32)" \
  PURPLE8_LICENSE_JWT="$(cat license.jwt)" \
  P8G_API_KEY="$(openssl rand -hex 24)"
fly deploy

Your instance is now at https://my-purple8.fly.dev — TLS terminated by Fly.

2.2 Fly notes & benchmarked sizing

RAM sizing is hardware-bounded, not corpus-bounded. Thanks to BrickCoreStorage (Purple8 Cortex) and CortexAutoConfig's brick seal-and-evict cycle, peak RSS never grows monotonically with corpus size $N$ — a 24 GB machine ingested 8.84M MS MARCO docs in ~9 GB peak RSS. You trade ingestion time, not memory, on smaller instances.
Enterprise node benchmark (performance-16x, 16 vCPU / 32 GB RAM): delivers 41,284 nodes/s burst ingest, 1,096 QPS concurrent hybrid search, 23 ms HTTP P95 (1024d with auth, WAL, AES-256-GCM, and RBAC all enabled), and 100% accuracy across all algorithm, RAG, SOC, and Quantum gates.
min_machines_running = 1 — a single Fly Volume attaches to one machine; keep it always-on so BrickWAL and the HNSW index stay warm.
Health checks: point Fly at GET /health.

2.3 DocIntel sidecar on Fly (optional)

Run DocIntel (v0.12.5) as a second Fly app and point it back at the graph:

bash

fly secrets set --app my-docintel \
  GRAPH__BASE_URL="https://my-purple8.fly.dev" \
  GRAPH__API_KEY="<the P8G_API_KEY>" \
  LLM__API_KEY="<your llm key>"

DocIntel (port 8200) parses 70+ document formats (PDF, Office, CAD/BIM IFC/DXF/STEP, SAP IDocs, scanned OCR) across 75+ languages and POSTs graph primitives to /ingest/commit.

3. AWS — for teams already in AWS

Two supported shapes. ECS Fargate + EFS is the general answer; App Runner is the lowest-effort if you can tolerate its constraints.

3.1 ECS Fargate + EFS (recommended)

Fargate has no persistent local disk, so all state goes to an EFS mount.

Task definition (excerpt):

json

{
  "family": "purple8-graph",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "3072",
  "volumes": [{
    "name": "p8g-data",
    "efsVolumeConfiguration": {
      "fileSystemId": "fs-0abc123",
      "transitEncryption": "ENABLED",
      "rootDirectory": "/purple8"
    }
  }],
  "containerDefinitions": [{
    "name": "graph-api",
    "image": "ghcr.io/purple8-technologies/purple8-graph:0.72.0",
    "portMappings": [{ "containerPort": 8000, "protocol": "tcp" }],
    "mountPoints": [{ "sourceVolume": "p8g-data", "containerPath": "/data" }],
    "environment": [
      { "name": "P8G_PORT", "value": "8000" },
      { "name": "P8G_DATA_PATH", "value": "/data" },
      { "name": "P8G_CORS_ORIGINS", "value": "https://app.yourco.com" },
      { "name": "PURPLE8_REQUIRE_LICENSE", "value": "1" }
    ],
    "secrets": [
      { "name": "P8G_JWT_SECRET",      "valueFrom": "arn:aws:ssm:...:parameter/p8g/jwt_secret" },
      { "name": "P8G_API_KEY",         "valueFrom": "arn:aws:ssm:...:parameter/p8g/api_key" },
      { "name": "PURPLE8_LICENSE_JWT", "valueFrom": "arn:aws:secretsmanager:...:secret/p8g/license" }
    ],
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"],
      "interval": 30, "timeout": 5, "retries": 3, "startPeriod": 30
    }
  }]
}

Front it with an ALB:

Target group → container port 8000, health check path /health.
HTTPS listener with an ACM cert → this is where TLS terminates.
Raise the target-group / idle timeout (default 60 s) above your longest MCP SSE session (/mcp/sse) — e.g. 3600 s — or long agent connections get cut.
Enable stickiness if you run >1 task and rely on SSE; the SSE session and its /mcp/messages/ POSTs must hit the same task. For a single stateful instance (the common case) run exactly one task and scale vertically.

Secrets: use SSM Parameter Store (SecureString) or Secrets Manager as above — never bake keys into the task definition env block.

3.2 AWS App Runner (lowest-effort)

App Runner runs the container image directly with a managed HTTPS endpoint. Caveats you must design around:

No native persistent block storage — attach an EFS mount via a VPC connector, or App Runner is only suitable for stateless/read-replica use. For a stateful primary, prefer ECS+EFS.
Set env/secrets in the App Runner service config; health check path /health.

3.3 AWS KMS for at-rest encryption

Purple8's envelope encryption integrates directly with AWS KMS — set KMS_PROVIDER=aws and KMS_KEY_ID to the key ARN. The task role needs kms:GenerateDataKey + kms:Decrypt. Full setup in KMS_GUIDE.md §4.3.

3.4 DocIntel on AWS

Run DocIntel as a second Fargate service in the same VPC; set GRAPH__BASE_URL to the graph's internal ALB/Service Connect DNS (no need to traverse the public internet) and GRAPH__API_KEY from Secrets Manager.

4. Integrate your application (REST / SDK)

Once the instance is up, apps talk to it two ways.

4.1 REST directly

bash

# Ingest text — two-step: preview (dry-run, extracts entities/relationships)…
curl -X POST https://<host>/ingest/preview \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Acme signed a supply contract with Globex in 2026.","source_name":"note-1"}'

# …then commit the reviewed payload to write it into the graph
curl -X POST https://<host>/ingest/commit \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ ...preview payload... }'

# Hybrid RAG query
curl -X POST https://<host>/rag/hybrid-query \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"question":"Who did Acme contract with?","k":8}'

Text/URL/document ingestion routes through DocIntel (v0.12.5, 70+ formats, 75+ languages) when PURPLE8_DOCINTEL_URL is set, and falls back to the built-in extractor otherwise. Agents get the same flow in one call via the MCP data.ingest_text or data.ingest_file tool.

4.2 Python SDK (in-process or client)

python

# pip install purple8-hyper-graph
from purple8_graph import GraphEngine

engine = GraphEngine("/data", auto_config=True)   # BrickCoreStorage + CortexAutoConfig bounded-RSS
engine.add_node("acme", labels=["Company"], properties={"name": "Acme"})
results = engine.vector_search(embedding, k=8)

Use the embedded GraphEngine when your service is the backend (single-process app); use the REST API when multiple services or a separate frontend must share one instance.

4.3 Frontend wiring (the "frontend-only" pattern)

A team using Purple8 writes only a frontend. Point it at the REST API, authenticate with a user JWT (POST /auth/login) or a scoped API key, and call /rag, /graph, /journey. Set P8G_CORS_ORIGINS to your frontend origin so the browser is allowed to call the API.

5. Integrate your AI agents (MCP — 125 tools across 16 namespaces)

Agents connect to the same instance over MCP (/mcp/sse or /mcp) — no extra deployment. Every tool uses dot-namespaced naming (graph.query, graph.hybrid_search, rag.hybrid_query, data.ingest_text, journey.define, schema.validate, quantum.optimize, evolution.suggest, sentinel.summary, guardrails.evaluate). Full per-client configs (Claude Desktop/Code/Web, VS Code, Cursor, Windsurf, Cline, Continue) are in MCP_CLIENTS.md.

Quick check against your deployment:

bash

curl -s -o /dev/null -w "%{http_code}\n" -X POST https://<host>/mcp -H "X-API-Key: $KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'   # 200 OK, 401 bad key

Before pointing agents at a cloud deployment, set P8G_PUBLIC_URL, disable proxy buffering on /mcp*, and raise the load-balancer idle timeout to ≥ 300 s (ALB default 60 s). Full checklist: MCP_CLIENTS.md §6.

6. Environment variable quick reference

Var	Default	Notes
`P8G_PORT`	`8000` (Docker) / `8100` (local CLI)	HTTP listen port
`P8G_DATA_PATH`	`./data`	Point at the mounted volume (`/data`) — else state is lost on redeploy
`P8G_JWT_SECRET`	—	Required; strong random; signs user JWTs
`P8G_API_KEY`	—	Bootstrap admin API key
`P8G_CORS_ORIGINS`	unset (blocked)	Comma-separated browser origins; unset = cross-origin blocked
`P8G_PUBLIC_URL`	request `base_url`	Public `https://<host>` of this instance. Set it behind any proxy/ALB — remote MCP sessions route tool calls back through it
`PURPLE8_LICENSE_JWT`	—	Enterprise license token (`PURPLE8_LICENSE_FILE` / `PURPLE8_LICENSE_DATA` also accepted)
`PURPLE8_REQUIRE_LICENSE`	`0`	`1` = fail closed with no license (Enterprise production)
`KMS_PROVIDER`	`local`	`local`/`vault`/`aws`/`gcp`/`azure`; pair with `KMS_KEY_ID`
`P8G_MAX_UPLOAD_MB`	`100`	Cap for file-library / ingest uploads
`P8G_CONTEXT_REQUIRE_TENANT`	off	Require a `tenant_id` on the call path (multi-tenant enforcement)

See DOCKER_QUICKSTART.md for the full cheat-sheet.

7. Production checklist

[ ] Persistent volume mounted; P8G_DATA_PATH points at it
[ ] P8G_JWT_SECRET set to a strong random value (not a placeholder)
[ ] PURPLE8_LICENSE_JWT set and PURPLE8_REQUIRE_LICENSE=1
[ ] TLS terminated in front (Fly automatic; AWS via ALB/ACM)
[ ] P8G_CORS_ORIGINS restricted to your real frontend origin(s)
[ ] KMS provider configured for at-rest encryption (KMS_GUIDE.md)
[ ] Health check on GET /health
[ ] LB idle timeout raised above longest MCP SSE session
[ ] Exactly one stateful primary task (scale vertically), or stickiness if >1
[ ] One named, least-privilege API key per connecting app/agent
[ ] Backups of the data volume scheduled (snapshot the Fly Volume / EFS)

Purple8 Hyper Graph — Developer Deployment & Integration Patterns (Fly, AWS & OpenShift) ​

0. The integration model in one picture ​

1. Prerequisites & Self-Hosted Licensing (2 Tiers) ​

2. Fly.io — recommended for cloud ​

2.1 Deploy ​

2.2 Fly notes & benchmarked sizing ​

2.3 DocIntel sidecar on Fly (optional) ​

3. AWS — for teams already in AWS ​

3.1 ECS Fargate + EFS (recommended) ​

3.2 AWS App Runner (lowest-effort) ​

3.3 AWS KMS for at-rest encryption ​

3.4 DocIntel on AWS ​

4. Integrate your application (REST / SDK) ​

4.1 REST directly ​

4.2 Python SDK (in-process or client) ​

4.3 Frontend wiring (the "frontend-only" pattern) ​

5. Integrate your AI agents (MCP — 125 tools across 16 namespaces) ​

6. Environment variable quick reference ​

7. Production checklist ​

See also ​

Purple8 Hyper Graph — Developer Deployment & Integration Patterns (Fly, AWS & OpenShift)

0. The integration model in one picture

1. Prerequisites & Self-Hosted Licensing (2 Tiers)

2. Fly.io — recommended for cloud

2.1 Deploy

2.2 Fly notes & benchmarked sizing

2.3 DocIntel sidecar on Fly (optional)

3. AWS — for teams already in AWS

3.1 ECS Fargate + EFS (recommended)

3.2 AWS App Runner (lowest-effort)

3.3 AWS KMS for at-rest encryption

3.4 DocIntel on AWS

4. Integrate your application (REST / SDK)

4.1 REST directly

4.2 Python SDK (in-process or client)

4.3 Frontend wiring (the "frontend-only" pattern)

5. Integrate your AI agents (MCP — 125 tools across 16 namespaces)

6. Environment variable quick reference

7. Production checklist

See also