Skip to main content
Use this path when an enterprise IT team wants source visibility, Git history, and a clean customization workflow. The default command runs the official prebuilt image, while the repository stays available for audit, configuration, overrides, and code changes. For the fastest pilot path without source checkout, use One-Command Install.

​
Prerequisites

  • Git.
  • Docker with the Compose v2 plugin.
  • Access to the Overlay source repository or customer fork.
  • A supported app-data backend: Postgres for self-hosted deployments, or Convex only when it is explicitly selected.
  • A separate Postgres database for Better Auth when Better Auth is selected.
  • Enterprise provider credentials for the providers you enable, such as OIDC, S3-compatible storage, and a model provider.

​
Install From Source

Open the configured app URL or the local forwarded port:
By default, docker compose up -d pulls ghcr.io/layernorm/overlay-web:latest. Use that moving tag only for exploration. For qualification or production, set an immutable release in .env, for example:
For the current end-to-end Postgres and Better Auth procedure, use Docker on EC2.

​
What The Repo Provides

The source checkout is still important even when the first run uses the official image:
  • src/, packages/, and convex/ for audit and source-level customization.
  • docker/docker-compose.yml for the default image-based runtime.
  • docker/docker-compose.build.yml for local source builds.
  • .env.enterprise.example for enterprise runtime variables.
  • docs/config/*.example.json for validated deployment profiles.
  • overlay.config.json for non-secret runtime config.

​
Customize Runtime Config

Prefer runtime config before editing product code:
Use .env for secrets and deployment-specific values. Use overlay.config.json for non-secret provider shape, feature gates, compliance profile, CSP additions, and capability defaults. Validate config from the source checkout:

​
Build After Code Changes

When the IT team edits source files, switch to the build override:
The build override compiles the local checkout and tags the image as overlay-web:local by default. Set OVERLAY_WEB_BUILD_IMAGE if the team wants another local tag.

​
Production Custom Image

For production, prefer building in CI and pushing to the enterprise registry:
Then deploy that image with the same Compose runtime:
This keeps production servers focused on running images, while Git and CI own source edits, review, builds, scanning, and provenance.

​
Updating

For source-visible installs without code changes:
For customized forks:
For production custom-image deploys, rebuild and push a new enterprise image tag, update OVERLAY_WEB_IMAGE, then run:

​
Troubleshooting