Skip to main content

​
Prerequisites

  • Docker 24+ and Docker Compose v2
  • Ports 3000, 5433, 6380, and 8081 free on your machine

​
Step 1 — Clone and configure

git clone https://github.com/pavancharak/parmanasystems-core.git
cd parmanasystems-core
cp .env.example .env
Open .env and set two required values: 
POSTGRES_PASSWORD=choose-a-strong-password
PARMANA_API_KEY=choose-a-secret-api-key
The remaining variables have working defaults for local development.

​
Step 2 — Start the stack

docker compose up -d
This starts four services:
ServicePortRole
postgres5433 (host)Audit database
redis6380 (host)Replay protection store
server3000Governance runtime
dashboard8081Audit dashboard
The server waits for Postgres to be healthy before starting. On first run, allow 15–20 seconds for all services to be ready.

​
Step 3 — Verify the runtime is up

curl http://localhost:3000/health
Expected response: 
{
  "status": "ok",
  "runtimeVersion": "1.0.0",
  "runtimeHash": "sha256:...",
  "verification": "ok",
  "audit_db": true,
  "signing_mode": "env",
  "capabilities": ["execute", "verify", "audit"],
  "supportedSchemaVersions": ["1.0.0"]
}
If audit_db is false, Postgres has not connected yet. Wait a few seconds and retry. If verification is not "ok", the signing key is not configured. Check PARMANA_SIGNING_PROVIDER and the corresponding key variables in .env.

​
Step 4 — Perform your first authority verification

curl -s -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -d '{
    "executionId": "quickstart-001",
    "policyId": "claims-approval",
    "policyVersion": "1.0.0",
    "signals": {
      "claimAmount": 1200,
      "customerTier": "gold",
      "priorFraudSignals": false
    }
  }' | jq .
Expected response: 
{
  "status": "approved",
  "requires_override": false,
  "attestation": {
    "executionId": "quickstart-001",
    "execution_fingerprint": "a3f8...",
    "policyId": "claims-approval",
    "policyVersion": "1.0.0",
    "decision": {
      "action": "approve",
      "requires_override": false,
      "reason": "Standard approval: claim within tier limit"
    },
    "execution_state": "completed",
    "signature": "...",
    "runtimeVersion": "1.0.0"
  }
}

​
Step 5 — Verify the attestation

Pass the complete attestation object from the previous response to /verify: 
curl -s -X POST http://localhost:3000/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -d '<paste the attestation object here>' | jq .
Expected response: 
{
  "valid": true,
  "checks": {
    "signature": "verified",
    "runtime": "verified",
    "schema": "verified"
  }
}

​
Step 6 — Open the dashboard

Navigate to http://localhost:8081. You should see the decision you just executed in the Decisions view.

​
Stop the stack

docker compose down
To also remove the Postgres volume (deletes all audit data): 
docker compose down -v

​
Troubleshooting

curl returns connection refused on port 3000 The server container may still be starting. Check logs: 
docker compose logs server --tail=30
Look for Server listening on http://0.0.0.0:3000. If you see [SYS-REPLAY-001] REDIS_URL is required, Redis did not connect: 
docker compose ps
docker compose logs redis --tail=20
Health endpoint returns "audit_db": false Postgres health check is still in progress. Wait 10 seconds and retry. If it persists: 
docker compose logs postgres --tail=20
Verify POSTGRES_PASSWORD in .env matches the value in the compose file. POST /execute returns 401 The Authorization: Bearer header must match the PARMANA_API_KEY value in .env. The header is required on all routes when PARMANA_API_KEY is set. POST /execute returns 422 with “Policy not found” The policy bundle claims-approval/1.0.0 must exist in the policies/ directory at the repository root. Verify: 
ls policies/claims-approval/1.0.0/
# Should contain: policy.json, bundle.manifest.json, bundle.sig
POST /execute returns 503 The signer or replay store is not configured. Check GET /health:
  • verification !== "ok" — signing key is not loaded. Check PARMANA_SIGNING_PROVIDER and key path/value in .env.
  • audit_db: false — Postgres not connected. Non-fatal for execution, but check Postgres logs.