> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Run the complete Parmana stack using Docker Compose in under 5 minutes

## Prerequisites

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

***

## Step 1 — Clone and configure

```bash theme={null}
git clone https://github.com/pavancharak/parmanasystems-core.git
cd parmanasystems-core
cp .env.example .env
```

Open `.env` and set two required values:

```bash theme={null}
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

```bash theme={null}
docker compose up -d
```

This starts four services:

| Service     | Port        | Role                    |
| ----------- | ----------- | ----------------------- |
| `postgres`  | 5433 (host) | Audit database          |
| `redis`     | 6380 (host) | Replay protection store |
| `server`    | 3000        | Governance runtime      |
| `dashboard` | 8081        | Audit dashboard         |

<Note>
  The server waits for Postgres to be healthy before starting. On first run, allow 15–20 seconds for all services to be ready.
</Note>

***

## Step 3 — Verify the runtime is up

```bash theme={null}
curl http://localhost:3000/health
```

Expected response:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```bash theme={null}
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:

```json theme={null}
{
  "valid": true,
  "checks": {
    "signature": "verified",
    "runtime": "verified",
    "schema": "verified"
  }
}
```

***

## Step 6 — Open the dashboard

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

***

## Stop the stack

```bash theme={null}
docker compose down
```

To also remove the Postgres volume (deletes all audit data):

```bash theme={null}
docker compose down -v
```

***

## Troubleshooting

**`curl` returns connection refused on port 3000**

The server container may still be starting. Check logs:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

***

<Cards>
  <Card title="First Authority Verification" href="/getting-started/first-authority-verification">
    Full flow with SDK code examples
  </Card>

  <Card title="Local Deployment" href="/docker/local">
    Complete docker-compose.yml reference
  </Card>

  <Card title="Production Deployment" href="/docker/production">
    Nginx, TLS, secrets, and backup strategy
  </Card>
</Cards>