For administrators

Setup Guide

Run the EPV server from published images. You need Docker and one compose file; nothing to build.

A single-host setup for evaluation and pilots. It is not a production-qualified deployment.

What you need

  • Docker Engine or Docker Desktop with Docker Compose v2
  • About 2 GB of free disk space for the images
  • For organization accounts: an OIDC identity provider such as Keycloak, Entra ID or Okta

Start the Docker stack

  1. Make an empty folder and download the two files:
  2. Save env.example as .env in the same folder. Or download both from a terminal:
    Terminal
    mkdir epv && cd epv
    curl -fsSLo compose.yml https://github.com/KasunRocz-Softwares/EPV-Site/releases/latest/download/compose.yml
    curl -fsSLo .env https://github.com/KasunRocz-Softwares/EPV-Site/releases/latest/download/env.example
  3. Open .env and give each required password a unique random value. Generate one with openssl rand -hex 24.
  4. Pull the images and start EPV:
    Terminal
    docker compose pull
    docker compose up -d
    docker compose ps

The first start creates the database and the encrypted-file bucket, then starts the API, the policy worker and the organization console.

View compose.yml
compose.yml
# Enterprise Personal Vault: single-host stack from published images.
#
# 1. Put this file and the .env template (renamed to .env) in an empty folder.
# 2. Fill in every value marked REQUIRED in .env.
# 3. docker compose pull && docker compose up -d
#
# This is a single-host setup for evaluation and pilots. It is not a production-qualified or
# highly available deployment; see https://qulaxy.com/EPV-Site/#status.
# PostgreSQL, Redis and the object store are only reachable inside the Compose network.

x-epv-image: &epv-api-image ghcr.io/kasunrocz-softwares/epv-api:${EPV_IMAGE_TAG:-latest}

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: epv
      POSTGRES_USER: epv
      POSTGRES_PASSWORD: ${EPV_DB_ADMIN_PASSWORD:?Set EPV_DB_ADMIN_PASSWORD in .env}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U epv -d epv']
      interval: 5s
      timeout: 3s
      retries: 10

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ['redis-server', '--appendonly', 'yes']
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 10

  rustfs:
    image: rustfs/rustfs:1.0.3-glibc
    restart: unless-stopped
    environment:
      RUSTFS_VOLUMES: /data/rustfs{0..3}
      RUSTFS_ADDRESS: 0.0.0.0:9000
      RUSTFS_CONSOLE_ENABLE: 'false'
      RUSTFS_ACCESS_KEY: ${EPV_OBJECT_STORAGE_USER:?Set EPV_OBJECT_STORAGE_USER in .env}
      RUSTFS_SECRET_KEY: ${EPV_OBJECT_STORAGE_PASSWORD:?Set EPV_OBJECT_STORAGE_PASSWORD in .env}
      # Single-volume layout; see the RustFS documentation before using multiple disks.
      RUSTFS_UNSAFE_BYPASS_DISK_CHECK: 'true'
      RUSTFS_OBS_LOGGER_LEVEL: error
    ports:
      # Browsers upload and download encrypted files here through short-lived signed URLs.
      - '${EPV_FILES_PORT:-9000}:9000'
    volumes:
      - object_storage_data:/data
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://127.0.0.1:9000/health >/dev/null']
      interval: 5s
      timeout: 3s
      retries: 10

  migrate:
    image: *epv-api-image
    restart: 'no'
    command: ['node', 'apps/api/dist/database/migrate.js']
    environment:
      NODE_ENV: production
      MIGRATION_DATABASE_URL: postgresql://epv:${EPV_DB_ADMIN_PASSWORD}@postgres:5432/epv
      EPV_APP_DB_PASSWORD: ${EPV_APP_DB_PASSWORD:?Set EPV_APP_DB_PASSWORD in .env}
      EPV_MIGRATOR_DB_PASSWORD: ${EPV_MIGRATOR_DB_PASSWORD:?Set EPV_MIGRATOR_DB_PASSWORD in .env}
      EPV_WORKER_DB_PASSWORD: ${EPV_WORKER_DB_PASSWORD:?Set EPV_WORKER_DB_PASSWORD in .env}
    depends_on:
      postgres:
        condition: service_healthy

  files-init:
    image: *epv-api-image
    restart: 'no'
    command: ['node', 'apps/api/dist/files/ensure-bucket.js']
    environment:
      S3_ENDPOINT: http://rustfs:9000
      S3_REGION: us-east-1
      S3_BUCKET: epv-encrypted-files
      S3_ACCESS_KEY: ${EPV_OBJECT_STORAGE_USER}
      S3_SECRET_KEY: ${EPV_OBJECT_STORAGE_PASSWORD}
      FILE_STORAGE_CORS_ORIGINS: ${EPV_CONSOLE_URL:-http://localhost:8080},chrome-extension://caijjlabajponibphckpeingakefhfpo
    depends_on:
      rustfs:
        condition: service_healthy

  api:
    image: *epv-api-image
    restart: unless-stopped
    environment:
      # Development mode allows local policy signing; production mode requires AWS KMS.
      NODE_ENV: development
      PORT: 3000
      LOG_LEVEL: info
      DATABASE_URL: postgresql://epv_app:${EPV_APP_DB_PASSWORD}@postgres:5432/epv
      REDIS_URL: redis://redis:6379
      # Invitation email: set SMTP_HOST, SMTP_FROM and INVITE_CONSOLE_URL together, or none of them.
      ADMIN_CONSOLE_URL: ${INVITE_CONSOLE_URL:-}
      SMTP_HOST: ${SMTP_HOST:-}
      SMTP_PORT: ${SMTP_PORT:-}
      SMTP_FROM: ${SMTP_FROM:-}
      SMTP_USER: ${SMTP_USER:-}
      SMTP_PASSWORD: ${SMTP_PASSWORD:-}
      SMTP_SECURE: ${SMTP_SECURE:-}
      OIDC_ISSUER: ${OIDC_ISSUER:-}
      OIDC_AUDIENCE: ${OIDC_AUDIENCE:-}
      OIDC_PASSWORD_AMR: ${OIDC_PASSWORD_AMR:-pwd}
      OIDC_TOTP_AMR: ${OIDC_TOTP_AMR:-otp}
      OIDC_WEBAUTHN_AMR: ${OIDC_WEBAUTHN_AMR:-}
      OIDC_WEBAUTHN_ACR: ${OIDC_WEBAUTHN_ACR:-}
      POLICY_SIGNING_MODE: local
      POLICY_SIGNING_KEY_ID: ${POLICY_SIGNING_KEY_ID:-}
      POLICY_SIGNING_PRIVATE_KEY_B64URL: ${POLICY_SIGNING_PRIVATE_KEY_B64URL:-}
      TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:-}
      # The console and the published extension (its ID is fixed for every installation).
      CORS_ALLOWED_ORIGINS: ${EPV_CONSOLE_URL:-http://localhost:8080},chrome-extension://caijjlabajponibphckpeingakefhfpo
      S3_ENDPOINT: http://rustfs:9000
      S3_PUBLIC_ENDPOINT: ${EPV_FILES_URL:-http://localhost:9000}
      S3_REGION: us-east-1
      S3_BUCKET: epv-encrypted-files
      S3_ACCESS_KEY: ${EPV_OBJECT_STORAGE_USER}
      S3_SECRET_KEY: ${EPV_OBJECT_STORAGE_PASSWORD}
    ports:
      - '${EPV_API_PORT:-3000}:3000'
    depends_on:
      migrate:
        condition: service_completed_successfully
      files-init:
        condition: service_completed_successfully
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test:
        [
          'CMD',
          'node',
          '-e',
          "fetch('http://127.0.0.1:3000/health/ready').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))",
        ]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s

  policy-propagation:
    image: *epv-api-image
    restart: unless-stopped
    command: ['node', 'workers/policy-propagation/dist/index.js']
    environment:
      NODE_ENV: production
      WORKER_DATABASE_URL: postgresql://epv_worker:${EPV_WORKER_DB_PASSWORD}@postgres:5432/epv
      REDIS_URL: redis://redis:6379
    depends_on:
      migrate:
        condition: service_completed_successfully
      redis:
        condition: service_healthy

  admin-web:
    image: ghcr.io/kasunrocz-softwares/epv-admin-web:${EPV_IMAGE_TAG:-latest}
    restart: unless-stopped
    # Written to /config.json when the container starts; no rebuild needed.
    environment:
      EPV_API_BASE_URL: ${EPV_API_URL:-http://localhost:3000}
      EPV_OIDC_ISSUER: ${OIDC_ISSUER:-}
      EPV_ADMIN_OIDC_CLIENT_ID: ${ADMIN_OIDC_CLIENT_ID:-}
      EPV_OIDC_AUDIENCE: ${OIDC_AUDIENCE:-}
    ports:
      - '${EPV_CONSOLE_PORT:-8080}:80'

  # Optional local copy of the EPV site and guides: docker compose --profile docs up -d
  site:
    image: ghcr.io/kasunrocz-softwares/epv-help:${EPV_IMAGE_TAG:-latest}
    profiles: ['docs']
    restart: unless-stopped
    ports:
      - '${EPV_SITE_PORT:-8090}:80'

volumes:
  postgres_data:
  redis_data:
  object_storage_data:
View the .env template
.env
# Enterprise Personal Vault settings. Save this file as .env next to compose.yml.
# Generate each password with:  openssl rand -hex 24
# Never commit the filled-in .env or share it.

# Image version to run. Pin a release tag (for example v0.1.0) for repeatable installs.
EPV_IMAGE_TAG=latest

# ---- REQUIRED: unique random passwords --------------------------------------------------
EPV_DB_ADMIN_PASSWORD=
EPV_APP_DB_PASSWORD=
EPV_MIGRATOR_DB_PASSWORD=
EPV_WORKER_DB_PASSWORD=
EPV_OBJECT_STORAGE_USER=epv_files
EPV_OBJECT_STORAGE_PASSWORD=

# ---- Addresses people's browsers use -------------------------------------------------------
# Use HTTPS addresses behind a reverse proxy for anything beyond a single test machine.
EPV_API_URL=http://localhost:3000
EPV_CONSOLE_URL=http://localhost:8080
EPV_FILES_URL=http://localhost:9000

# Host ports (change if they are already in use).
EPV_API_PORT=3000
EPV_CONSOLE_PORT=8080
EPV_FILES_PORT=9000
EPV_SITE_PORT=8090

# ---- Organization sign-in (OIDC) ------------------------------------------------------------
# Leave empty to run without organization accounts. Register two public clients (no secret):
# one for the console (redirect http://localhost:8080/ or your console URL) and one for the
# extension (redirect https://caijjlabajponibphckpeingakefhfpo.chromiumapp.org/).
OIDC_ISSUER=
OIDC_AUDIENCE=
ADMIN_OIDC_CLIENT_ID=

# ---- Policy signing (optional) ---------------------------------------------------------------
# Generate a key pair with the command in the setup guide. Give the public key to users for the
# extension settings page; keep the private key only here.
POLICY_SIGNING_KEY_ID=
POLICY_SIGNING_PRIVATE_KEY_B64URL=

# ---- Invitation email (optional) ---------------------------------------------------------------
# Leave every value empty to disable email. To enable it, set SMTP_HOST, SMTP_FROM and
# INVITE_CONSOLE_URL (the console address used in invitation links); for example port 587.
INVITE_CONSOLE_URL=
SMTP_HOST=
SMTP_PORT=
SMTP_FROM=
SMTP_USER=
SMTP_PASSWORD=
SMTP_SECURE=
Use HTTPS beyond a single test machine

Put a reverse proxy with TLS in front of the API, console and file ports, then set EPV_API_URL, EPV_CONSOLE_URL and EPV_FILES_URL to the HTTPS addresses. The database, cache and object store are never exposed outside the Compose network.

Open the services

Organization console
http://localhost:8080
Encrypted files
http://localhost:9000 (used by browsers through signed links)
This site, offline (optional)
docker compose --profile docs up -d, then port 8090

The console shows a locked state until sign-in is configured. That is expected; there is no default username or password.

Connect your identity provider

EPV uses OIDC Authorization Code with PKCE. In your identity provider, register two public clients with no client secret:

Console client redirect
http://localhost:8080/ or your EPV_CONSOLE_URL
Extension client redirect
https://caijjlabajponibphckpeingakefhfpo.chromiumapp.org/

Then set OIDC_ISSUER, OIDC_AUDIENCE and ADMIN_OIDC_CLIENT_ID in .env and apply them. No rebuild is needed; the console reads its settings when the container starts.

Terminal
docker compose up -d
These are public client settings

Issuer, audience and client IDs are identifiers. Never put an identity provider client secret into EPV's settings.

Sign organization policies

Policies are signed so the extension can tell they came from you. Generate a key pair with the API image:

Terminal
docker compose run --rm --no-deps api node -e "const c=require('crypto');const k=c.generateKeyPairSync('ed25519');console.log('POLICY_SIGNING_KEY_ID=policy-1');console.log('POLICY_SIGNING_PRIVATE_KEY_B64URL='+k.privateKey.export({type:'pkcs8',format:'der'}).toString('base64url'));console.log('Policy public key for the extension: '+k.publicKey.export({type:'spki',format:'der'}).subarray(12).toString('base64url'))"

Copy the two POLICY_SIGNING_ lines into .env and run docker compose up -d. Share the key ID and the public key with your users for the extension settings. Keep the private key only in .env.

Add the first owner

Sign in to your identity provider once, find your subject (sub), then create the organization with you as its owner:

Terminal
docker compose run --rm migrate node apps/api/dist/database/provision-member.js \
  --issuer <issuer-url> \
  --subject <oidc-subject> \
  --organization-name "<organization name>" \
  --role owner

This uses the administrative database connection inside the Compose network. The API itself runs with a restricted database role.

Connect the extension

Users install the extension from the download page, open its Settings page, and enter:

API address
Your EPV_API_URL
Issuer, client ID, audience
The extension client from your identity provider
Policy key ID and public key
From the key you generated above

To set this for everyone and lock it, push the same values through Chrome enterprise policy for extension caijjlabajponibphckpeingakefhfpo. The download page has an example.

Update and back up

To update, set EPV_IMAGE_TAG in .env to a newer release tag, then pull and restart:

Terminal
docker compose pull
docker compose up -d

Data lives in the postgres_data, redis_data and object_storage_data volumes. Back them up before updating. docker compose down keeps them; adding -v deletes them permanently.

Troubleshooting

Compose says a variable is required

A required password in .env is still empty. Fill it in and run docker compose up -d again.

“Sign in with your organization” is disabled

Set OIDC_ISSUER, OIDC_AUDIENCE and ADMIN_OIDC_CLIENT_ID in .env, then run docker compose up -d.

The API keeps restarting

Run docker compose logs api. Email settings must be all set or all empty: SMTP_HOST, SMTP_FROM and INVITE_CONSOLE_URL go together.

The extension can create a vault but cannot connect

Local vaults do not need a server. For sync, check the API address and identity provider values on the extension's Settings page, and that the extension client allows the redirect shown there.

Encrypted file upload fails

Browsers must reach EPV_FILES_URL. Check that the file port is open and that docker compose ps shows the object store as healthy.