Node.js without Docker

The web app is a standard Next.js app. Run it with Node.js anywhere that can reach your Convex backend and the providers in overlay.config.json.

Build and start

You need Node.js 22 or newer and npm 11 or newer.

git clone https://github.com/LayerNorm/overlay-web.git
cd overlay-web
npm ci
npm run build
OVERLAY_CONFIG_FILE=overlay.config.json npm run start

Set at least NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_CONVEX_URL, INTERNAL_API_SECRET, INTERNAL_SERVICE_AUTH_SECRET and the session secrets in the process environment. See Environment variables for the full list. Keep secrets in your platform’s secret store and the deployment’s shape in overlay.config.json. NEXT_PUBLIC_* values are read at build time as well as at run time, so build once per environment.

Common shapes

Without billing:

{
  "billing": { "provider": "none", "stripe": {} },
  "capabilities": { "billing": false }
}

Without WorkOS, using your OIDC provider:

{
  "auth": {
    "provider": "oidc",
    "allowDevFallbacks": false,
    "workos": {},
    "oidc": {
      "issuerUrl": "https://idp.example.com",
      "clientId": "overlay-web",
      "clientSecret": "oidc_client_secret_placeholder",
      "audience": "overlay-api"
    }
  },
  "capabilities": { "sso": true }
}

For SSO with sign-in pages managed by Overlay, prefer Better Auth.

Check it works

npm run check:config

Then, with the app running:

/app/work loads the app shell, and Settings opens.
/api/v1/capabilities shows the redacted configuration in non-production environments.
Features you turned off answer capability_disabled instead of failing.
Uploading a file works once the object store and its bucket exist.

Before a real rollout, go through Release verification.

Overview

Install

Configure

Operate

Enterprise

Licensing

Node.js without Docker

Build and start

Common shapes

Check it works

​Build and start

​Common shapes

​Check it works

Build and start

Common shapes

Check it works