Skip to content

Public Demo Deployment on Render

OpenEA Community's public demonstration environment can run on Render using a web service and PostgreSQL. This deployment pattern is intended for a disposable public demo, not as the recommended production architecture for organizations self-hosting OpenEA.

The standard production/self-hosted model remains Docker Compose with separate web and worker containers. See Install with Docker Compose.

Demo architecture

GitHub main branch
      ↓
GitHub Actions checks
      ↓
Render deployment
      ↓
Render web service ─────► PostgreSQL
   ├── Uvicorn/FastAPI
   └── OpenEA worker

The worker runs as a background process in the same Render web container because the public demo is intentionally optimized for a small free-tier footprint.

Deployment sequence

The demo startup sequence is:

alembic upgrade head
      ↓
commit-aware demo reset check
      ↓
reset/reseed only for a new deployed commit
      ↓
start OpenEA worker in background
      ↓
exec Uvicorn as the main process

Uvicorn must remain the main container process so Render can detect and supervise the listening web port.

A minimal startup pattern is:

python -m app.workers.metrics_worker &
exec uvicorn app.main:app --host 0.0.0.0 --port "${PORT:-10000}"

Commit-aware demo reset

The public demo is editable, so visitors can create, edit, and archive architecture records. OpenEA's demo startup script uses Render's deployed Git commit identifier to distinguish a new application deployment from a normal cold start/restart.

Expected behavior:

  • Same deployed commit: preserve current demo changes.
  • New deployed commit: reset the demo repository and reseed Northstar Financial.
  • Forced demo reset: an administrator can intentionally request a reset for the same commit using the configured demo-control setting.

This prevents a free-service wake-up or normal restart from erasing user changes while still ensuring each new release starts from a known demo baseline.

Database URL

Render may provide a PostgreSQL URL such as:

postgresql://user:password@host/database

OpenEA normalizes supported postgresql:// and legacy postgres:// values to the SQLAlchemy Psycopg 3 dialect:

postgresql+psycopg://...

The same normalization is used by the application and Alembic.

Health check

Use:

/health/ready

as the Render health-check path. This confirms both the FastAPI process and database connectivity.

Background calculations

The same worker used in Docker Compose runs in the Render web container. It processes event-driven jobs and the Platform Administrator schedules configured under Management → Background Processing.

Default schedules are:

  • Analytics & Metrics: every 6 hours
  • Findings Evaluation: every 1 hour

See Worker and Background Calculations.

Environment variables

The demo deployment uses the normal OpenEA configuration plus demo-specific controls such as:

  • DEMO_RESET_ON_DEPLOY
  • DEMO_FORCE_RESET
  • DEMO_ADMIN_PASSWORD
  • DEMO_USER_PASSWORD

Secrets and the database connection string should be managed through Render rather than committed to the repository.

See Environment Variables.

Protect the public login with reCAPTCHA

For the public demo, OpenEA Community can use Google reCAPTCHA v2 with the visible I'm not a robot checkbox.

  1. Register the demo hostname in the Google reCAPTCHA configuration. If you expose both the generated Render hostname and a custom hostname such as demo.openea.dev, register every hostname that users will actually use.
  2. In the Render web service, add these secret environment variables:
RECAPTCHA_SITE_KEY=<your-site-key>
RECAPTCHA_SECRET_KEY=<your-secret-key>
  1. Deploy the updated OpenEA image.
  2. Sign in as a Platform Administrator.
  3. Open Management → Settings.
  4. Confirm Site key configured: Yes and Secret key configured: Yes.
  5. Enable reCAPTCHA on login and save.
  6. Sign out and confirm the checkbox appears on /login.

The keys are not stored in PostgreSQL. Only the enabled/disabled setting is persisted there. If reCAPTCHA is enabled but the deployment keys are later removed, interactive login fails closed until the keys are restored or an already-authenticated Platform Administrator disables the setting.

The public demo therefore has an intentional Google runtime dependency on the login page when this control is enabled. Normal self-hosted and offline installations should leave it disabled.

Automatic deployment from GitHub

The intended flow is:

commit / merge to main
      ↓
GitHub Actions
      ↓
checks pass
      ↓
Render automatically deploys

The Blueprint can use Render's checks-pass deployment trigger so a failed GitHub Actions run does not replace the working demo.

Custom domain

The public demo can be exposed through:

https://demo.openea.dev

Configure the custom domain in Render after the generated Render URL works, then add the DNS record requested by Render and allow TLS provisioning to complete.

Free-tier expectations

Treat free-tier demo infrastructure as disposable. Service sleep/cold starts, database limits, and provider retention policies can change over time. Do not use the public demo as a production system or as the only copy of architecture data.