Deployment and access

Deployment shapes

The console is built per deployment shape. The on-premises and Lite builds leave every Hub and Auth0 host blank, and a blank host means "no host" everywhere it is read, never a default. That is what keeps a customer's browser from calling OpenLegacy's Hub or Auth0 tenant.

In Lite there is no Hub at all: the backend reports no identity provider, so the console skips the account shell entirely rather than waiting on a licence it can never fetch, and surfaces Help and Global Settings as header buttons.

Installing a bundle. Both shapes ship as a bundle: unzip it, copy .env.example to .env (every required value is marked) and run docker compose -f docker-compose.onprem.yml up -d, or docker-compose.lite.yml for Lite. The bundle carries its own README.md, BUILD.md and ENVIRONMENT.md, the last listing every variable each shape reads. No registry serves OL Next images yet, so the bundle ships the jar and you build the image locally. Check it is up with GET /api, not /health, and confirm the shape you built with GET /api/v1/config/public.

Inside an on-premises OL Hub. The on-premises bundle can also run beside an OL Hub installation, which then hosts OL Next in its own shell. Set the Hub's OL_NEXT_URL=http://ol-next:8080 and re-run the Hub's ./install.sh: the Hub serves OL Next at /ol-next and its API at /ol-next-backend/. On start, OL Next creates and migrates the database schema of every active Hub tenant (OL_NEXT_MIGRATE_ON_START, on by default in the on-premises compose file); a tenant added later is set up on its first request.

Pointing the console at your Hub. GET /api/v1/config/public also tells the console where the Hub services are, so one image serves every environment. Set OL_HUB_PLATFORM_URL, OL_HUB_BACKEND_DOMAIN, OL_HUB_AUTH_SERVICE_URL, OL_HUB_BACKOFFICE_URL, OL_HUB_RUNTIME_SERVICE_URL, OL_AUTH0_DOMAIN, OL_AUTH0_CLIENT_ID and OL_AUTH0_CONNECTION. They form two independent sets, the five Hub URLs and the one Auth0 client, and each is published whole or not at all, so an on-premises install can report its own Hub without an Auth0 client it does not have.

Signing in

Whether OL Next asks you to sign in depends on how the backend is configured, not on the build; the console asks the backend on startup and adapts:

• On-premises, standalone: no identity provider. The console opens straight into the workspace with no sign-in, acting as a single administrator.
• SaaS: sign-in runs through OL Hub single sign-on, and the header's tenant pill shows which tenant the session operates as. Opened at its own URL, the console redirects you to the Hub login page and back.
• On-premises, Hub Enterprise: sign-in runs through your organisation's Keycloak realm, which hosts the login page. All users share one workspace.

Account settings exist only on a backend with an identity provider: open them from your avatar's user menu, or at /account, for your profile, API keys, licenses and team. Without one there is no user menu, and Global Settings is reached from the header gear button.

Tenants and access

On-premises standalone has a single built-in tenant. In SaaS or the OpenLegacy Platform, each Hub tenant is isolated from the others: files, database schema, and play and RPC sessions all belong to the signed-in tenant. You don't have access to this workspace means the application belongs to another account, usually a bookmark from before you switched accounts.

• 401 Unauthorized: you are not signed in, or the session expired. Sign in again. On-premises standalone does not return 401 for a missing login.
• 403 Forbidden: you are signed in, but this tenant is not allowed to perform that action. In SaaS, ENFORCE application access also returns 403 when the tenant is not entitled to OL Next; the console then opens an application-unavailable page instead of a workspace whose every request fails.
• Session ended: the console says the play or RPC session has ended and offers a fresh one. Sessions close after 30 minutes idle (OL_SESSION_IDLE_TIMEOUT_SEC), and a hosted deployment also ends them when the server instance holding the session restarts. Nothing else is lost: your application, operations and generated files are untouched.

A hosted deployment may run several server instances. Every session of the same operation shares one database, whichever instance you reach; sample data lives in memory, so it starts empty again if the instance holding it restarts. Replay the operation to reseed it.

Running inside the OpenLegacy Platform

OL Next runs standalone at its own URL, or embedded as a remote inside the OpenLegacy Platform shell at /ol-next. The hosted SaaS console is the embedded one: sign in to the OpenLegacy Platform and open OL Next there. It is the same console either way; three things differ when embedded: OL Next appears in the platform header's app switcher, the platform shell owns sign-in, so OL Next never shows its own login page, and the shell owns the route, so the browser's back and forward buttons step through your OL Next history the same way they do standalone.

Calling the API without a browser

A hosted console accepts a Hub account API key as well as a signed-in session. Generate one under API access in Global Settings (it is shown once) and send it as an x-api-key header on any /api request, including the MCP endpoint. The key belongs to your tenant and carries your own access; revoke it in OpenLegacy Hub. On-premises installs use the MCP key on the same page instead, because there is no Hub to issue one.

Where Help goes

On the cloud console both Help affordances open this OL Edge documentation in a new tab, which is the copy kept current. The on-premises and Lite bundles show the guide that ships inside them, because such a site need not reach edge.openlegacy.com.