Deployment

Don't want to manage infrastructure?

Revisium Cloud — managed platform, zero ops, free to start. Sign up with Google or GitHub.

Standalone

Single command, embedded PostgreSQL, zero configuration:

npx @revisium/standalone@latest

Open http://localhost:9222. No auth by default.

Option	Default	Description
`--port`	first free port from `9222`	HTTP port; scans upward until one is free
`--pg-port`	first free port from `5440`	Embedded PostgreSQL port; scans upward until one is free
`--auth`	`false`	Enable authentication (`admin` / `admin`)
`--data`	`~/.revisium`	Data directory for embedded PostgreSQL, persisted JWT secret, and default local uploads
`-h`, `--help`	—	Print CLI help

# Custom port with auth
npx @revisium/standalone@latest --port 3000 --auth

# Fixed embedded PostgreSQL port
npx @revisium/standalone@latest --pg-port 5555

# Persistent data
npx @revisium/standalone@latest --data ./revisium-data

If the default HTTP or PostgreSQL port is busy, standalone picks the next free port unless you pass a fixed --port or --pg-port. The supported data-directory option is --data; the old accidental --data-dir alias is no longer accepted.

MCP endpoint available at /mcp:

claude mcp add --transport http revisium http://localhost:9222/mcp

Best for: local development, PoC, AI agent integrations, demos.

Docker Compose

Full stack with PostgreSQL:

services:
  db:
    image: postgres:17.4-alpine
    restart: always
    environment:
      POSTGRES_DB: revisium
      POSTGRES_USER: revisium
      POSTGRES_PASSWORD: change-me-to-a-secure-password
    volumes:
      - pgdata:/var/lib/postgresql/data

  revisium:
    image: revisium/revisium:latest
    pull_policy: always
    depends_on:
      - db
    ports:
      - 8080:8080
    environment:
      DATABASE_URL: postgresql://revisium:change-me-to-a-secure-password@db:5432/revisium?schema=public
      ADMIN_PASSWORD: change-me

volumes:
  pgdata:

docker-compose up -d

Open http://localhost:8080. Login: admin / value of ADMIN_PASSWORD.

With Redis and S3

services:
  db:
    image: postgres:17.4-alpine
    restart: always
    environment:
      POSTGRES_DB: revisium
      POSTGRES_USER: revisium
      POSTGRES_PASSWORD: change-me
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: always

  revisium:
    image: revisium/revisium:latest
    pull_policy: always
    depends_on:
      - db
      - redis
    ports:
      - 8080:8080
    environment:
      DATABASE_URL: postgresql://revisium:change-me@db:5432/revisium?schema=public
      CACHE_ENABLED: 1
      CACHE_L2_REDIS_URL: redis://redis:6379
      CACHE_BUS_HOST: redis
      CACHE_BUS_PORT: 6379
      STORAGE_PROVIDER: s3
      FILE_PLUGIN_PUBLIC_ENDPOINT: https://files.example.com/files
      S3_ENDPOINT: https://s3.amazonaws.com
      S3_BUCKET: my-revisium-files
      S3_REGION: us-east-1
      S3_ACCESS_KEY_ID: AKIA...
      S3_SECRET_ACCESS_KEY: ...
      ADMIN_PASSWORD: change-me

volumes:
  pgdata:

Updating

docker-compose pull
docker-compose up -d

Database migrations run automatically on startup.

Docker (Single Container)

Bring your own PostgreSQL:

docker run -d \
  -p 8080:8080 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/revisium?schema=public \
  -e ADMIN_PASSWORD=change-me \
  revisium/revisium:latest

Kubernetes

Use the official Docker image with your Helm charts or manifests:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: revisium
spec:
  replicas: 1
  selector:
    matchLabels:
      app: revisium
  template:
    metadata:
      labels:
        app: revisium
    spec:
      containers:
      - name: revisium
        image: revisium/revisium:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: database-url
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: jwt-secret
        - name: ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: revisium-secrets
              key: admin-password

For multi-pod deployments:

Set JWT_SECRET explicitly — auto-generated per process won't work across pods
Set CACHE_ENABLED=1 with CACHE_L2_REDIS_URL and CACHE_BUS_HOST/CACHE_BUS_PORT for cache sync between pods
Use a managed PostgreSQL service

For schema migrations in K8s, see CI/CD.

Docs Search with Typesense

docs.revisium.io can use Typesense behind the same docs domain.

Recommended production layout:

docs container serves static Docusaurus pages
Kubernetes ingress routes /search/* to the internal Typesense service
docs-search-indexer runs the stateless typesense-docsearch-scraper

This keeps the browser pointed at the docs origin instead of a separate public Typesense endpoint.

Configuration

All configuration is done via environment variables.

Required

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db?schema=public`

Authentication

Variable	Default	Description
`JWT_SECRET`	auto-generated	JWT signing secret. Set explicitly in production and multi-pod deployments
`ADMIN_PASSWORD`	`admin`	Default admin password
`TRUST_PROXY`	unset	Express `trust proxy` value. Required behind ingress, load balancers, or reverse proxies so Express uses forwarded protocol and client IP metadata
`CORS_ORIGIN`	development: reflect request origin; production: same-origin only	Comma-separated credentialed CORS allowlist. Set explicitly when the Admin UI and core API use different origins
`COOKIE_SECURE`	`NODE_ENV === 'production'`	Sets the cookie `Secure` flag. Use `true` for HTTPS deployments
`COOKIE_SAMESITE`	`lax`	Cookie `SameSite` value: `lax`, `strict`, or `none`. `none` requires `COOKIE_SECURE=true`

Browser login uses cookies, so proxy, CORS, and cookie settings must agree:

Deployment shape	Recommended values	Notes
Local HTTP	`COOKIE_SECURE=false`, `COOKIE_SAMESITE=lax`	Standalone applies these defaults when `PUBLIC_URL` is local HTTP
Same-site HTTPS	`COOKIE_SECURE=true`, `COOKIE_SAMESITE=lax` or `strict`	Works when Admin UI and API share the same site
HTTPS behind proxy or ingress	`TRUST_PROXY=<hop-count>`, `CORS_ORIGIN=https://your-admin-origin`, `COOKIE_SECURE=true`, `COOKIE_SAMESITE=lax`	Use an explicit CORS allowlist for credentialed browser requests
Cross-site embed or separate site	`COOKIE_SECURE=true`, `COOKIE_SAMESITE=none`, explicit `CORS_ORIGIN`	Browsers reject `SameSite=None` cookies unless they are also `Secure`

Cache

Variable	Default	Description
`CACHE_ENABLED`	`0`	Enable caching (`1` to enable)
`CACHE_L1_MAX_SIZE`	—	Max items in L1 (in-memory) cache
`CACHE_L2_REDIS_URL`	—	Redis URL for L2 cache
`CACHE_BUS_HOST`	—	Redis host for cache bus (multi-pod invalidation)
`CACHE_BUS_PORT`	—	Redis port for cache bus
`CACHE_DEBUG`	`0`	Enable cache debug logging

File Storage

Variable	Default	Description
`STORAGE_PROVIDER`	self-hosted: unset; standalone: `local`	Storage backend: `local`, `s3`, or unset. Set `s3` explicitly for S3 deployments, or leave unset only when all `S3_*` variables are present so self-hosted S3 autodetection can select S3; otherwise uploads are disabled
`STORAGE_LOCAL_PATH`	self-hosted: `./uploads`; standalone: `<data>/uploads`	Local filesystem upload directory. In self-hosted mode, `./uploads` is relative to the process working directory
`FILE_PLUGIN_PUBLIC_ENDPOINT`	local: `http://localhost:{PORT}/files`; standalone: `PUBLIC_URL/files`	Exact public URL prefix used in file metadata. Required for S3; include `/files` in the value if your deployment serves files under `/files`
`S3_ENDPOINT`	—	S3-compatible endpoint URL
`S3_BUCKET`	—	Bucket name
`S3_REGION`	—	AWS region
`S3_ACCESS_KEY_ID`	—	Access key
`S3_SECRET_ACCESS_KEY`	—	Secret key

Standalone stores uploads on the local filesystem by default and serves them from /files/.... For Docker, Kubernetes, and multi-pod deployments, use S3-compatible storage unless you intentionally mount shared local storage. Revisium does not append /files to an explicit FILE_PLUGIN_PUBLIC_ENDPOINT; it uses the value as the URL prefix.

SMTP (Email)

Variable	Description
`SMTP_HOST`	SMTP server hostname
`SMTP_PORT`	SMTP port
`SMTP_USER`	SMTP username
`SMTP_PASS`	SMTP password

Endpoint Configuration

Variable	Default	Description
`GRAPHQL_HIDE_NODE_TYPES`	`false`	Hide generated GraphQL node query types
`GRAPHQL_HIDE_FLAT_TYPES`	`false`	Hide generated GraphQL flat query types
`GRAPHQL_HIDE_MUTATIONS`	`false`	Hide generated draft-revision GraphQL mutations
`GRAPHQL_PREFIX_FOR_TABLES`	project name	Prefix generated table GraphQL types
`GRAPHQL_PREFIX_FOR_COMMON`	project name	Prefix generated common GraphQL types
`GRAPHQL_FLAT_POSTFIX`	`Flat`	Postfix for flat GraphQL types
`GRAPHQL_NODE_POSTFIX`	empty	Postfix inserted before node type suffixes

See API Configuration for details.

API Keys

Variable	Default	Description
`INTERNAL_API_KEY_ENDPOINT`	Auto-generated (monolith)	Internal key for endpoint-to-core communication. Set explicitly in microservice mode.
`API_KEY_DEFAULT_EXPIRATION_DAYS`	`365`	Default expiration for new API keys
`API_KEY_MAX_PER_USER`	`10`	Max personal API keys per user
`API_KEY_MAX_SERVICE_PER_ORG`	`100`	Max service API keys per organization

In monolith/standalone mode, internal keys are derived automatically from JWT_SECRET. For multi-replica deployments, JWT_SECRET must be set explicitly so all pods derive the same key.

Service Communication (Microservice Mode)

Variable	Description
`CORE_API_URL`	URL of revisium-core service
`CORE_API_USERNAME`	Service account username (deprecated — use `INTERNAL_API_KEY_ENDPOINT`)
`CORE_API_PASSWORD`	Service account password (deprecated — use `INTERNAL_API_KEY_ENDPOINT`)

In the all-in-one Docker image, these are configured automatically.

Infrastructure

PostgreSQL

The only required dependency. PostgreSQL 14 or higher.

JSONB columns for row data and table schemas
Copy-on-write for revisions — commits don't duplicate unchanged data
Indexes on system fields and JSONB paths for query performance
Recommended: managed PostgreSQL (AWS RDS, Google Cloud SQL, etc.) for production

Redis (Optional)

Used for L2 cache and multi-pod cache invalidation:

L1 cache — in-memory cache per process (CACHE_L1_MAX_SIZE)
L2 cache — Redis shared across pods (CACHE_L2_REDIS_URL)
Cache bus — Redis pub/sub for cache invalidation across pods (CACHE_BUS_HOST, CACHE_BUS_PORT)

Without Redis, Revisium uses in-memory caching with PostgreSQL-based bus (fine for single-instance). Set CACHE_ENABLED=1 to enable caching.

File Storage (Optional)

Revisium supports local filesystem storage and S3-compatible storage:

Local filesystem storage for standalone or simple single-node deployments
Any S3-compatible storage (AWS S3, MinIO, DigitalOcean Spaces, etc.)
Files up to 50 MB (not yet configurable)
Metadata stored in PostgreSQL, binaries in the configured storage backend

Without STORAGE_PROVIDER and without a complete S3_* configuration, file fields are available in schemas but upload is disabled.

SMTP (Optional)

For email notifications (e.g., user invitations).

Requirements

Component	Required	Notes
PostgreSQL 14+	Yes	The only required dependency
Node.js 20+	Standalone/CLI only	Not needed for Docker
File storage backend	Optional	Standalone uses local storage by default; production deployments usually use S3-compatible storage
Redis	Optional	For caching and multi-pod sync

Standalone​

Docker Compose​

With Redis and S3​

Updating​

Docker (Single Container)​

Kubernetes​

Docs Search with Typesense​

Configuration​

Required​

Authentication​

Cache​

File Storage​

SMTP (Email)​

Endpoint Configuration​

API Keys​

Service Communication (Microservice Mode)​

Infrastructure​

PostgreSQL​

Redis (Optional)​

File Storage (Optional)​

SMTP (Optional)​

Requirements​