> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js without Docker

> Build and run the Overlay web app as a plain Node.js process.

The web app is a standard Next.js app. Run it with Node.js anywhere that can reach your [Convex backend](https://getoverlay.io/docs/self-hosting/install/self-hosted-convex.md) and the providers in `overlay.config.json`.

## Build and start

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

```bash theme={null}
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](https://getoverlay.io/docs/self-hosting/configure/environment.md) 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:

```json theme={null}
{
  "billing": { "provider": "none", "stripe": {} },
  "capabilities": { "billing": false }
}
```

Without WorkOS, using your OIDC provider:

```json theme={null}
{
  "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](https://getoverlay.io/docs/self-hosting/configure/authentication/backends.md).

## Check it works

```bash theme={null}
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](https://getoverlay.io/docs/self-hosting/operate/release-verification.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.