Getting Started

Set up Open Privacy Suite and run it locally in minutes.

Prerequisites

Docker and Docker Compose v2+
Make
Git

Development mode

In development mode, the proxy uses mock ZK verification. No real Privado wallet needed — use the flask icon on the login page for instant mock authentication.

Evaluating the product?

make quickstart brings up a self-contained demo — two banks and a regulator on one chain, with seeded identities and ready-to-use tokens — and verifies the privacy story live. ONBOARDING.md in the repo root is the guided tour; the steps below bring up the plain development stack instead.

Installation

Clone the repository

git clone https://github.com/gateway-fm/open-privacy-suite.git
cd open-privacy-suite

Start the stack

make run

This starts PostgreSQL, Anvil (local Ethereum node), the proxy backend, and the admin frontend.

Open the admin UI

open http://localhost:5173

Click the flask icon below the QR code for instant mock login. Mock users are automatically granted the admin claim, so the admin dashboard is accessible immediately.

Services

Service	Port	Description
proxy-backend	8080	API server
proxy-frontend	5173	Admin UI
postgres	5432	Database
anvil	8545	Local Ethereum node

Full-stack dev (privacy mode — proxy + block-explorer + chain-indexer)

make run only brings up the proxy itself. For an end-to-end privacy-mode environment that includes the block-explorer (frontend + BFF), the chain-indexer, and a second postgres for the explorer, use make full-stack-dev:

make full-stack-dev

This calls scripts/privacy-dev-up.sh, which:

Resolves the sibling-repo paths (BLOCK_EXPLORER_PATH, CHAIN_INDEXER_PATH) and verifies they exist.
Generates .env.privacy.dev on first run (random secrets — POSTGRES passwords, JWT secrets, ADMIN_API_TOKEN). Delete the file to rotate (run down -v first to drop encrypted volumes).
Auto-creates rpc-namespaces.json from the example so the EXTRA_RPC_NAMESPACES_FILE mount doesn't fail.
Brings the stack up via docker-compose.privacy.dev.yml, then waits for the proxy-backend healthcheck.

Required layout (sibling clones)

/your/dev/dir/
  ├── open-privacy-suite/  ← you are here
  ├── block-explorer/      ← clone of gateway-fm/ops-explorer
  └── chain-indexer/       ← clone of gateway-fm/ops-indexer (optional;
                             the dev compose pulls the published image
                             by default — see Configuration → INDEXER_VERSION)

Override paths if your layout differs:

BLOCK_EXPLORER_PATH=/path/to/block-explorer \
CHAIN_INDEXER_PATH=/path/to/chain-indexer \
  make full-stack-dev

Services started

Service	Port	Source	Description
proxy-backend	8080	local build	Open Privacy Suite API (mock-login + mock-signatures enabled)
proxy-frontend	5173	local build	Open Privacy Suite admin UI
privacy-postgres	—	image	Open Privacy Suite database
anvil	8545	image	Local Ethereum node
redis	—	image	Per-user rate limit + session store
chain-indexer	50051 (gRPC)	published image, tag `INDEXER_VERSION` (default `0.3.0`)	Block indexer feeding the BFF
indexer-postgres	—	image	Chain-indexer database
block-explorer-api	—	local build from `BLOCK_EXPLORER_PATH/backend`	Block-explorer BFF (privacy-mode build, chain-indexer client compiled out)
block-explorer-frontend	3001	local build from `BLOCK_EXPLORER_PATH/frontend`	Block-explorer UI (nginx)
block-explorer-postgres	—	image	Block-explorer database

URLs after start:

Open Privacy Suite backend → http://localhost:8080
Open Privacy Suite frontend → http://localhost:5173 (mock-login)
Block-explorer frontend → http://localhost:3001

Dev only — mock auth is on

This stack uses ALLOW_MOCK_LOGIN=true and MOCK_SIGNATURES=true. Both are runtime-gated AND require the mockauth build tag (-tags mockauth). The prod compose (docker-compose.privacy.yml) compiles them out entirely. Do not point the dev manifest at any customer-facing environment.

Stop with docker compose -f docker-compose.privacy.dev.yml down. Add -v to wipe all volumes.

Useful Commands

Command	Description
`make run`	Start all services
`make stop`	Stop all services
`make restart`	Restart all services
`make logs`	View live logs
`make status`	Show service status
`make clean`	Stop and remove volumes

LAN Access

To access from other devices on your network:

BASE_URL="http://YOUR_LAN_IP:8080" make run

Replace localhost with your LAN IP in all URLs.

Custom Ports

BACKEND_HOST_PORT=8081 POSTGRES_HOST_PORT=5433 BASE_URL="http://YOUR_IP:8081" make run

Next Steps

Architecture — understand the system design
Authentication — ZK-proof auth and SSO flows
RBAC — role-based access control
Configuration — environment variables reference