From source

Use this setup for development and local evaluation. It runs the dashboard, API, and worker as separate processes and lets Docker provide PostgreSQL if you do not already have it.

This guide uses the repository root docker-compose.yml. That contributor file builds from the checkout and exposes PostgreSQL to local tools; it is separate from the public compose.production.yaml deployment.

Prerequisites

Node.js 22
pnpm 10.30.3 through Corepack or a compatible installation
PostgreSQL 16 with pgvector
a reachable Docling Serve endpoint
OpenSSL

Prepare the repository

Install dependencies:
Terminal window
```
pnpm install
```
Create the environment file:
Terminal window
```
cp .env.example .env
```

Generate an encryption key and set it in .env:

openssl rand -hex 32

ARKIVRA_ENCRYPTION_KEYS=1:<generated-64-hex-character-key>

Keep the default local split-origin values unless you need different ports:

ARKIVRA_PUBLIC_URL=http://localhost:5173
ARKIVRA_DATABASE_URL=postgres://arkivra:arkivra@127.0.0.1:5432/arkivra
ARKIVRA_DATA_PATH=./var/default
ARKIVRA_DOCLING_URL=http://127.0.0.1:5001

The API environment loader reads the repository .env and apps/arkivra-server/.env when present.

Optional Privatemode provider

The API, worker, and dashboard run with the pnpm commands below; no Arkivra image is needed. The current Privatemode adapter requires a separately running Privatemode encryption proxy. An API key alone does not replace that proxy.

If the proxy listens locally on port 8080, add these values to the repository .env:

ARKIVRA_PRIVATEMODE_PROXY_URL=http://127.0.0.1:8080/v1
PRIVATEMODE_API_KEY=<your-api-key>

Use the trusted proxy’s actual address if it runs elsewhere. Do not use api.privatemode.ai as the proxy URL. Restart both API and worker after changing the environment. Once the dashboard is running, open Administration → AI Settings, refresh Privatemode, choose the models, and enable AI. See Providers and models for capabilities and the encryption boundary.

Start PostgreSQL and Docling

Start only the repository PostgreSQL service:

docker compose up -d postgres

Start Docling separately. The native or container options are documented in Document processing.

Verify both dependencies before continuing:

docker compose ps postgres
curl http://127.0.0.1:5001/health

Migrate and run

Apply database migrations:
Terminal window
```
pnpm db:migrate
```
Start these commands in separate terminals:
Terminal window
```
pnpm dev:api
```
Terminal window
```
pnpm dev:worker
```
Terminal window
```
pnpm dev:web
```
Open the dashboard at http://localhost:5173.

The API listens on http://localhost:1221; the dashboard development server proxies /api requests to it. The worker does not expose a browser page, but it must remain running for document processing, semantic indexing, backup jobs, restore jobs, and scheduled maintenance.

Useful checks

Run focused checks for the app you changed:

pnpm --dir apps/arkivra-server test:fast
pnpm --dir apps/arkivra-client test:fast
pnpm --dir apps/arkivra-docs check

Check migration/schema agreement with:

pnpm db:check

For a production source deployment, use built artifacts and a process manager, run migrations before starting a web-capable process, and give the API and worker the same stable configuration and data paths. The repository Docker image already encodes this startup order.

Crafted with care by Jasnan Thachaparamban