Deploy Eneo

Deploy Eneo in production with Docker Compose. This page is the primary deployment guide: it takes you from prerequisites to a verified installation, then links to focused guides for storage, authentication, and AI providers.

Start here

Architecture overview

Eneo uses a small service stack. Durable content defaults to bounded PostgreSQL-inline bytes; an optional private object-store byte plane can be enabled when needed.

Prerequisites

Before deploying, ensure you have:

• Docker and Docker Compose v2+ installed
• Domain name with DNS pointing to your server
• SSL certificate (Let’s Encrypt via Traefik, or your own PKI/CA)
• An API key for at least one AI provider. Providers are added after the first login in Admin → Models (see AI Provider Configuration)

System Requirements

Quick start

Before running docker compose up:

• replace every your-domain.com, changeme, and CHANGEME;
• generate the database password, JWT_SECRET, and URL_SIGNING_KEY;
• set PUBLIC_ORIGIN in the backend and frontend files;
• have at least one AI provider API key ready for Admin → Models;
• create the proxy_tier network;
• download the complete release.env and release.json bundle from the selected release;
• leave the optional object-store block commented unless you have chosen and prepared that storage path.

mkdir eneo-deployment && cd eneo-deployment
# Download release.json and release.env from the selected GitHub release into this directory.
# Use its exact source revision for the deployment files too.
ENEO_SOURCE_REVISION=$(python3 -c 'import json; print(json.load(open("release.json"))["revision"])')
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/docker-compose.yml"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/docker-compose.object-content.yml"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/env_backend.template"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/env_frontend.template"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/env_db.template"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/.env.template"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/setup.py"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/docker-compose.without-tools.yml"
 
# Only if you plan to run optional modules (see "Optional modules" below)
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/docker-compose.modules.yml"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/env_modules.template"
curl -fLO "https://raw.githubusercontent.com/eneo-ai/eneo/$ENEO_SOURCE_REVISION/docs/deployment/env_module_ttt.template"

cp env_backend.template env_backend.env
cp env_frontend.template env_frontend.env
cp env_db.template env_db.env
cp .env.template .env
python3 setup.py
chmod 600 .env env_backend.env env_frontend.env env_db.env

# Generate JWT_SECRET (backend token signing key)
JWT_SECRET=$(openssl rand -hex 32)
echo "JWT_SECRET=$JWT_SECRET"
 
# Generate URL_SIGNING_KEY
echo "URL_SIGNING_KEY=$(openssl rand -hex 32)"
 
# Generate database password (MUST match in env_backend.env AND env_db.env)
echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)"

# Create external network for Traefik
docker network create proxy_tier
 
# Start all services
docker compose --env-file .env --env-file release.env up -d
 
# Check status
docker compose ps
 
# View logs
docker compose logs -f

Network Isolation

The Docker Compose stack uses five networks:

PostgreSQL and Redis are only attached to data_net. They are not reachable from frontend, Traefik, or module containers, and they have no outbound internet access.

Verify the isolation after upgrading:

# Should fail: frontend can no longer resolve the database
docker exec eneo_frontend getent hosts db
 
# Should succeed
docker exec eneo_backend python -c "import socket; socket.getaddrinfo('db', 5432)"
curl -fsS https://your-domain.com/version

Environment Configuration

The tables below cover the values you must set or are most likely to change. The templates in docs/deployment/ are the complete reference: every variable is listed there with its shipped value and a comment.

# .env
REDIS_PASSWORD=<output of: openssl rand -hex 32>

# Development (with uv)
uv run python -m eneo.cli.generate_encryption_key
 
# Production (Docker)
docker compose run --rm backend python -m eneo.cli.generate_encryption_key
 
# Alternative (Python)
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

openssl rand -base64 24

Signed file references

When an assistant may open attached files itself (the “Låt assistenten öppna bifogade filer själv” switch, inline_file_text=false), or when a tool edits an attached or generated image, the model receives each file as a signed link instead of its content:

{FILE_REFERENCE_BASE_URL}/api/v1/files/{file_id}/original/download/?token=...

Eneo’s built-in file tool, the bundled tool runtime and external MCP servers receive the same link. The built-in file tool verifies the token locally and never makes an HTTP request. The tool runtime and external MCP servers redeem the link over HTTP, so the Eneo backend must be reachable at FILE_REFERENCE_BASE_URL from the network where they run. This is independent of where the file bytes live: originals stored in PostgreSQL and originals stored in object storage are served through the same endpoint.

The download endpoint accepts no session cookie or API key. The signed token is the only credential: it names the file and tenant, is signed with URL_SIGNING_KEY, and expires after FILE_REFERENCE_URL_EXPIRY_SECONDS (default 15 minutes, at most one hour). Anyone holding an unexpired link can download the file. Treat every MCP server that receives file links as a recipient of the file contents, and enable such servers only where that data flow is acceptable.

Three controls limit the exposure of a link:

• A tool call may only carry links to the files of its own conversation: the attachments and generated files Eneo minted links for in that request. A link to any other file in the arguments, even a valid one pasted in by a user or returned by another tool, stops the call before the MCP server is contacted.
• Every redemption is audited as file_original_downloaded under File operations, with the caller’s address and user agent, next to the file_original_download_link_created entry written when the link was minted.
• The token is stripped from tool-call arguments and results before they are stored, shown in the chat, or replayed to the model. Only the tool that was called ever holds the live link. Deleting the file revokes every outstanding link for it.

Choose FILE_REFERENCE_BASE_URL by where the MCP servers run:

On a private network with no route from the MCP server to the backend, the tool call fails. The model is told the link is valid, so it reports that the tool cannot reach the file rather than asking the user to upload it again. The fix is always network reachability or a corrected base URL, never a re-upload.

Object Content Storage

The reference stack defaults to bounded PostgreSQL-inline content. An optional Compose profile runs private, Eneo-built SeaweedFS. Deployments that need an existing storage platform or multi-node availability can instead use another compatible endpoint, including MinIO. Both object-store paths use the same contract and fail closed when configuration or the database/bucket binding does not match.

Policy changes take effect without a backend or worker restart. They affect eligible new writes only; existing content stays in its recorded backend until an explicit verified migration moves it. The product has one provider-neutral object-store path, not vendor-specific storage modes. Admin > File storage also compares Eneo’s recorded file-content size with the entire PostgreSQL database on disk. These figures overlap: inline file content is part of both totals, and the PostgreSQL figure also includes searchable text, pgvector embeddings, tables, indexes, and internal storage. The page does not report remaining host or bucket capacity. See What do the storage-usage figures mean? for the exact boundaries.

The same page presents current status before configuration: the active target, object-store health, file-content distribution, and migration state appear first. PostgreSQL allocation and detailed effective limits remain available as technical details instead of competing with routine storage decisions.

The page also shows the portable multipart envelope when it constrains object-store session uploads. FastAPI/Starlette multipart parsing happens before route admission and may use temporary disk. Eneo rejects an oversized File or Icon before its own capture/spool or any storage mutation. Operators must use ingress/request-body limits and configure and monitor temporary-disk capacity to protect that earlier parsing boundary.

Follow Object Content Storage for the image digest, credentials, MinIO policy, TLS, readiness, backup, and troubleshooting steps. See Object Content Architecture for the control-plane boundary, lifecycle, reconciliation, and image supply chain.

Optional modules

Modules are optional web applications (for example speech-to-text) that run next to Eneo on their own domain. A module container joins only module_net, calls the backend at http://backend:8000 with a scoped sk_ service key, and can never reach PostgreSQL or Redis. Users log in through their Eneo session; modules have no IdP configuration of their own.

Modules ship as a Compose overlay that is inert until you enable a profile:

cp env_modules.template env_modules.env
cp env_module_ttt.template env_module_ttt.env
# In .env, uncomment and set ENEO_DOMAIN, MODULE_TTT_DOMAIN and MODULE_STT_VERSION
 
docker compose -f docker-compose.yml -f docker-compose.modules.yml \
  --profile speech-to-text up -d

The module domain must point at the same Traefik ingress; the overlay routes it over eneo_module_net. See Module Authentication for the login handoff, ticket exchange, and session refresh contract, and Module administration below for the admin-side prerequisites.

Reverse Proxy Requirements

Any reverse proxy (Traefik, nginx, HAProxy, Caddy) must meet these requirements:

Routing:

These are the exact prefixes the shipped Traefik labels route to the backend.

Headers:

• X-Forwarded-Proto - original protocol (https)
• X-Forwarded-For - client IP address
• Host - original host header

Requirements:

• WebSocket support (for real-time features)
• TLS termination with valid certificate

Using nginx Instead of Traefik

upstream frontend {
    server frontend:3000;
}
 
upstream backend {
    server backend:8000;
}
 
server {
    listen 443 ssl http2;
    server_name eneo.example.com;
 
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
 
    # API routes to backend
    location /api/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
 
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
 
    # SCIM provisioning (identity provider calls /scim/v2/...)
    location /scim/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 
    location /docs {
        proxy_pass http://backend;
        proxy_set_header Host $host;
    }
 
    location /openapi.json {
        proxy_pass http://backend;
    }
 
    location /version {
        proxy_pass http://backend;
    }
 
    # Everything else to frontend
    location / {
        proxy_pass http://frontend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

API Key Hierarchy

Eneo uses environment and user/service credentials for separate tasks.

Both are sent in the X-API-Key header (configurable with API_KEY_HEADER_NAME).

Credentials API

Manage AI provider credentials per tenant using the sysadmin API.

curl -X PUT "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials/{provider}" \
  -H "X-API-Key: your-super-api-key" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-..."}'

curl "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials" \
  -H "X-API-Key: your-super-api-key"

curl -X DELETE "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials/{provider}" \
  -H "X-API-Key: your-super-api-key"

Supported {provider} values: openai, anthropic, azure, mistral, ovhcloud, gemini, cohere

Crawler Settings API

Configure crawling behavior per tenant. From 2.3 the endpoint rejects unknown keys with 422, including the settings of the retired crawl feeder and tenant semaphore (tenant_worker_concurrency_limit, crawl_feeder_* and similar). Values stored earlier for those keys are ignored.

curl -X PUT "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key" \
  -H "Content-Type: application/json" \
  -d '{"closespider_itemcount": 20000, "crawl_heartbeat_interval_seconds": 300}'

curl "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key"

curl -X DELETE "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key"

Enabling Features

After deployment, some features require additional configuration in the Admin panel.

Crawler & Document Upload

When applying source-URL migration 202609071200, stop the API and both workers, then restart all publishers on the same version. Old publishers identify website documents by title; the new version uses their source URL. The migration preserves metadata and citation IDs and reports ambiguous legacy URLs for review.

Apps (Voice/Audio Features)

Sysadmin API Access

To use system administration endpoints (tenants, credentials, crawler settings), set the API key in env_backend.env:

ENEO_SUPER_API_KEY=your-secure-api-key

Module administration

Configure modules in Admin → Modules with an ordinary signed-in administrator holding the modules permission. The organization is derived from the session; module administration does not require a separate environment key or a tenant ID. The container side is covered in Optional modules.

Troubleshooting

Common Issues

Database Shared Memory Errors

Symptom: some requests fail with HTTP 500, and the database log shows could not resize shared memory segment ... No space left on device. The disk is not full: PostgreSQL ran out of /dev/shm, a small memory area inside the container. Docker and Podman limit it to 64 MB unless the service sets shm_size.

PostgreSQL uses it for queries it runs in parallel, and each database connection that has run such a query keeps a small part of it for as long as the connection lives. With many pooled connections and large queries, 64 MB is too little.

Fix: set shm_size: 1gb on the db service, as the reference docker-compose.yml does, and recreate the container:

docker compose up -d db

The value is an upper limit, not memory reserved up front. Recreating the container briefly interrupts Eneo; the data stays in its volume. Set stop_grace_period: 2m on the service too, as the reference file does: with the default 10 seconds, a busy database can be killed before its shutdown checkpoint finishes and then needs crash recovery when it starts.

Until you can recreate the container, stop PostgreSQL from running queries in parallel. This takes effect without a restart and makes large queries slower:

docker compose exec db psql -U postgres -d eneo -c "ALTER SYSTEM SET max_parallel_workers_per_gather = 0;"
docker compose exec db psql -U postgres -d eneo -c "SELECT pg_reload_conf();"

If the errors continue, restart the backend so that its database connections reconnect with the new setting.

Undo it after raising shm_size:

docker compose exec db psql -U postgres -d eneo -c "ALTER SYSTEM RESET max_parallel_workers_per_gather;"
docker compose exec db psql -U postgres -d eneo -c "SELECT pg_reload_conf();"

Debug Mode

Enable detailed logging for troubleshooting:

# In env_backend.env
LOGLEVEL=DEBUG

Then restart and view logs:

docker compose restart backend
docker compose logs -f backend

Service Health Checks

The backend is not published on a host port in the reference stack, so run these through your public domain (or from inside a container).

# Check all services are running
docker compose ps
 
# Liveness: the API process answers
curl -fsS https://your-domain.com/api/livez
 
# Health: backend, worker heartbeat, and object-content readiness (503 if the worker is unhealthy)
curl -fsS https://your-domain.com/api/healthz
 
# Readiness alias of /api/healthz on current images (older released images only have /api/healthz)
curl -fsS https://your-domain.com/api/readyz
 
# Detailed crawler diagnostics (requires the deployment's super API key)
curl -fsS https://your-domain.com/api/healthz/crawler \
  -H "X-API-Key: $ENEO_SUPER_API_KEY"
 
# Running backend version
curl -fsS https://your-domain.com/version
 
# Check database
docker compose exec db psql -U postgres -d eneo -c "SELECT version()"
 
# Check Redis
docker compose exec redis redis-cli ping
 
# View db-init logs (for first-run issues)
docker logs eneo_db_init

Container Logs

# All services
docker compose logs -f
 
# Specific service
docker compose logs -f backend
 
# Last 100 lines
docker compose logs --tail=100 backend worker

Maintenance

One version for the application

The standard stack includes the isolated tools runtime. Frontend, backend and runtime share one version and source revision; workers use the backend image. Download release.env and release.json from the selected release. The bundle pins all application images by digest and is published only after the combined image checks pass.

Run python3 setup.py to generate the missing runtime credential without changing existing settings or printing secrets. Use both environment files:

docker compose --env-file .env --env-file release.env up -d

Use the same environment-file arguments for later Compose commands. Commands that do not show those arguments need them too. To avoid repeating them, run export COMPOSE_ENV_FILES=.env,release.env once in the shell (Docker Compose 2.24 or later). Without a bundle, python3 setup.py --version X.Y.Z selects one explicit version. There are no default application latest tags.

For upgrades, replace the complete bundle together. For rollback, restore the previous bundle and observe the release’s database rollback requirements. Do not independently update the tools image. Remove old runtime image pins and the optional runtime overlay/profile; the old overlay is a compatibility shim for one release. Existing capability settings and external providers are kept.

The Admin > Tools status panel reports connectivity, credentials, version, confinement and file-origin issues. A version mismatch warns while calls remain allowed. Installing the runtime does not enable capabilities. To omit it, add -f docker-compose.yml -f docker-compose.without-tools.yml; stop any existing runtime container first. Ordinary chat and backend readiness remain independent.

Backups

Database backup with pg_dump (recommended):

# Create timestamped database backup
docker compose exec -T db pg_dump -U postgres eneo | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
 
# Restore from backup (if needed)
gunzip -c backup_20250108.sql.gz | docker compose exec -T db psql -U postgres eneo

Volume backup (for complete recovery):

# Stop services first
docker compose down
 
# Backup PostgreSQL data volume
docker run --rm -v eneo_eneo_postgres_data:/data -v $(pwd):/backup ubuntu \
  tar czf /backup/postgres_volume_$(date +%Y%m%d).tar.gz /data
 
# Backup Redis data volume (optional)
docker run --rm -v eneo_eneo_redis_data:/data -v $(pwd):/backup ubuntu \
  tar czf /backup/redis_volume_$(date +%Y%m%d).tar.gz /data

If object-store rows exist, also archive eneo_eneo_object_content_data while backend, worker, and the object-content service are stopped, or take the matching versioned snapshot in your external provider. Follow the object-content backup and restore procedure, including checksum and skew-recovery checks.

Updating Eneo

docker compose exec -T db pg_dump -U postgres eneo | gzip > backup_$(date +%Y%m%d).sql.gz

docker compose --env-file .env --env-file release.env stop backend worker crawler-worker
docker compose --env-file .env --env-file release.env pull
docker compose --env-file .env --env-file release.env run --rm db-init
docker compose --env-file .env --env-file release.env up -d
docker compose --env-file .env --env-file release.env ps

docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  config --quiet
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  stop backend worker crawler-worker
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  pull
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  run --rm db-init
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  up -d
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  ps

curl -fsS https://eneo.example.eu/api/readyz \
  | jq -e '.detail.object_content.code == "ready"'

docker compose logs --since=30m worker \
  | grep "File/Icon legacy backfill"

docker image prune -a

docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  stop backend worker crawler-worker object-content
# Restore the matching PostgreSQL dump and object-store snapshot as described
# in the linked procedure, then start the pinned versions:
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  up -d
curl -fsS https://eneo.example.eu/api/readyz \
  | jq -e '.detail.object_content.code == "ready"'

Scaling

The reference docker-compose.yml sets a fixed container_name on every service, so docker compose up --scale ... is refused. To run more than one backend or worker replica, define additional services without container_name (or run the images under an orchestrator) and place the backend replicas behind your load balancer. Additional workers are safe. Crawls run only on crawler-worker services, each with its own /tmp. WORKER_MAX_JOBS applies per process, while CRAWL_JOB_CONCURRENCY_LIMIT and CRAWL_JOB_TENANT_CONCURRENCY_LIMIT cap running crawls across all crawler workers. Set CRAWL_JOB_TENANT_CONCURRENCY_LIMIT to the same value on the backend and every worker.

Related Documentation

• AI Provider Configuration - Configure AI models and providers
• Multi-Tenant OIDC Federation - Enterprise SSO setup
• Single-Tenant OIDC - Simple SSO setup
• SCIM Provisioning - Automated user and group provisioning
• SharePoint Integration - Connect SharePoint and OneDrive
• Module Authentication - Login handoff contract for optional modules
• Authentication Architecture - Technical authentication details
• System Architecture - Complete architecture overview
• Object Content Storage - Configure SeaweedFS, MinIO, backups, and readiness
• Release SBOMs and attestations - Verify shipped image digests and provenance

Run the Next beta alongside the existing app

The existing Svelte frontend remains ghcr.io/eneo-ai/eneo-frontend. The optional Next frontend uses ghcr.io/eneo-ai/eneo-web-next, published and pinned in the same release bundle (release.env sets ENEO_WEB_NEXT_IMAGE). Deploy both against one backend from one bundle. They share accounts, permissions, conversations, assistants, files, workers and database changes. Beta writes are real writes to the same data; this is not a separate sandbox.

Use a separate HTTPS hostname, for example beta.example.com, rather than a path prefix. Keep the existing app and backend PUBLIC_ORIGIN unchanged. The beta proxies API and streaming requests server-side to the shared backend. No additional database, Redis, worker or backend instance is needed.

1. Back up the existing database and storage, and rehearse the upgrade on staging. Apply backend migrations once with the backend release. The beta’s feedback/provider-status migrations follow the release’s existing chain; confirm alembic heads reports a single head.

2. Copy docs/deployment/env_web_next.template to env_web_next.env. Generate a separate SESSION_SECRET with openssl rand -base64 48, and set LEGACY_APP_URL=https://app.example.com for the return link in the beta profile menu. Protect the file as you protect other deployment secrets.

3. Set WEB_NEXT_HOST=beta.example.com in the deployment .env. The image comes from the release bundle’s ENEO_WEB_NEXT_IMAGE, so the beta always runs the build verified with the backend you deploy. Merge the optional overlay into the reference stack:

   docker compose --env-file .env --env-file release.env \
     -f docker-compose.yml -f docker-compose.web-next.yml --profile web-next up -d

4. For backend-managed federation, add https://beta.example.com/login/callback to each applicable federation configuration’s additional_redirect_uris, and register the same URI with the identity provider. The existing canonical callback stays registered. Use backend-managed authentication for the beta rollout. The separate frontend-managed OIDC flow remains experimental: concurrent requests can reuse a one-time rotating refresh token and invalidate the session. Refresh ownership is not coordinated across requests or replicas. Before releasing that mode, implement shared refresh coordination and validate the intended provider’s rotation behavior. Its development configuration uses the beta’s OIDC_* variables and the client callback https://beta.example.com/auth/callback.

5. For SharePoint and Confluence, retain OAUTH_CALLBACK_URL for the existing UI and add this backend runtime variable (a JSON array):

   OAUTH_CALLBACK_URLS=["https://beta.example.com/integrations/callback/token/"]

   Register both full callback URLs with the provider, including the trailing slash. The backend accepts only exact registered values and binds the chosen callback to the initiating user’s single-use OAuth state. Existing clients that omit a callback keep using the default. Restart the backend after changing its environment; finish or restart in-flight integration logins during upgrade.

6. Verify password/federated login, logout, streaming chat, files, tenant permissions and both integration providers in each UI before inviting users. Each UI has its own host-only session cookie. SSO can reuse the provider session, but a local logout in one UI does not necessarily log out the other.

Enable the invitation banner

Set these Svelte frontend runtime variables and restart that frontend:

SHOW_NEW_APP_BANNER=true
NEW_APP_URL=https://beta.example.com

The flag defaults to false. Both an enabled flag and a valid HTTP(S) destination are required. The invitation appears in the signed-in shell and opens a new tab, leaving the current app available. Setting the flag back to false hides it; the beta remains reachable by its URL. The banner is discoverability, not access control.

To withdraw the beta, disable the invitation and stop the web-next service or remove its ingress. Keep the shared backend and database running. Do not downgrade the shared database simply to turn off the beta; a backend rollback is a separate operation that requires a tested migration/restore plan and preserved user data.

Before release, require the normal CI/E2E checks, source/dependency/secret scans and the deployment’s application-image security checks. Review the temporary dependency mitigation in frontend/patches/SECURITY.md. Scanner success alone does not prove that authentication, tenant separation or accessibility is correct in the actual deployment; complete the staging checks with the configured providers.