SimplaixSimplaix Gateway

Deployment

Install and run Simplaix Gateway in production.

Prerequisites

  • Node.js 22+ (or Docker)
  • PostgreSQL 15+ (recommended for production; SQLite is supported for single-node deployments)
  • pnpm (if building from source)

The fastest way to get a production-ready Gateway with PostgreSQL.

1. Clone the repository

git clone https://github.com/simplaix/simplaix-gateway.git
cd simplaix-gateway

2. Create your .env

cp .env.example .env

Edit .env with production values:

JWT_SECRET=<strong-random-secret>          # openssl rand -hex 32
CREDENTIAL_ENCRYPTION_KEY=<hex-32-bytes>   # openssl rand -hex 32
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=<strong-password>
POSTGRES_PASSWORD=<db-password>
GATEWAY_PUBLIC_URL=https://gateway.yourdomain.com

3. Start

docker compose up -d

The Gateway starts on port 3001 and PostgreSQL on 5432. The admin user is created automatically on first boot from ADMIN_EMAIL / ADMIN_PASSWORD.

Option 2: Build from Source

1. Install dependencies

git clone https://github.com/simplaix/simplaix-gateway.git
cd simplaix-gateway
pnpm install

2. Build

pnpm build

3. Configure

cp .env.example .env
# Edit .env with your production values

4. Run migrations

pnpm db:migrate

5. Start

node dist/server.js

Environment Variables

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string — postgresql://user:pass@host/db
JWT_SECRETYesSecret for signing/verifying JWTs (min 32 chars)
CREDENTIAL_ENCRYPTION_KEYYes32-byte hex key for encrypting stored credentials
PORTNoHTTP port (default: 3001)
JWT_ISSUERNoJWT issuer claim (default: simplaix-gateway)
JWT_AUDIENCENoJWT audience claim
JWT_EXTERNAL_ISSUERSNoJSON array of external OIDC/JWT issuers
ADMIN_EMAILNoAuto-create admin on first boot
ADMIN_PASSWORDNoPassword for auto-created admin
GATEWAY_PUBLIC_URLNoPublic base URL — used in OAuth callbacks and pairing links
OAUTH_CALLBACK_BASE_URLNoOverride OAuth callback base separately from GATEWAY_PUBLIC_URL

Generating secrets

# JWT secret
openssl rand -hex 32

# Credential encryption key
openssl rand -hex 32

External JWT issuers

To accept JWTs from an external identity provider (e.g. Azure AD, Auth0):

# Shared secret
JWT_EXTERNAL_ISSUERS='[{"issuer":"https://auth.example.com","secret":"shared-secret","audience":"simplaix-gateway"}]'

# OIDC / JWKS (Azure AD, etc.)
JWT_EXTERNAL_ISSUERS='[{"issuer":"https://login.microsoftonline.com/TENANT/v2.0","jwksUri":"https://login.microsoftonline.com/TENANT/discovery/v2.0/keys","audience":"api://simplaix-gateway"}]'

Database

PostgreSQL (production)

DATABASE_URL=postgresql://gateway:password@localhost:5432/gateway

SQLite (single-node)

DATABASE_URL=file:./gateway.db

SQLite requires no setup but does not support horizontal scaling. Use PostgreSQL for any multi-instance deployment.

Create the First Admin

If you did not set ADMIN_EMAIL / ADMIN_PASSWORD, create an admin manually after the server is running:

gateway admin create --email admin@example.com --password changeme --name "Admin"

Or via the API:

curl -X POST https://<your-gateway-url>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"changeme"}'

Verify

gateway status

Or check the health endpoint:

curl https://<your-gateway-url>/health

Next Steps

Configuration

Architecture

Authentication

Human-in-the-Loop Confirmations

SSE-based real-time confirmation workflow for sensitive operations.

Authentication Overview

JWT, API key, and runtime-token authentication modes in the gateway.

On this page

PrerequisitesOption 1: Docker Compose (Recommended)Option 2: Build from SourceEnvironment VariablesGenerating secretsExternal JWT issuersDatabasePostgreSQL (production)SQLite (single-node)Create the First AdminVerifyNext Steps