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
- Make an empty folder and download the two files:
-
Save
env.exampleas.envin the same folder. Or download both from a terminal:Terminalmkdir 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 -
Open
.envand give each required password a unique random value. Generate one withopenssl rand -hex 24. -
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
# 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
# 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=
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
- API readiness
- http://localhost:3000/health/ready
- 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 yourEPV_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.
docker compose up -d
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:
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:
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:
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.