Environment Variables

This page documents every environment variable that oCore reads at startup. Variables are organized by subsystem. Required variables must be set for the application to start.

Database

The DATABASE_URL is read by the backend service. The POSTGRES_* variables are read by the PostgreSQL Docker image during initialization. In Docker Compose, DATABASE_URL is constructed from the POSTGRES_* values.

JWT / Authentication

Generate a strong JWT secret:

openssl rand -base64 48

SMTP / Email

In development, the defaults point to a local Mailpit instance. For production, configure a real SMTP provider (e.g., AWS SES, SendGrid, Postmark, or your own mail server).

OAuth Providers

Both OAuth providers are optional. If the client ID and secret are not set, the corresponding login button is hidden in the dashboard.

To set up GitHub OAuth:

1. Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App
2. Set the Authorization callback URL to https://ocore.example.com/api/auth/oauth/github/callback
3. Copy the Client ID and Client Secret to your .env file

To set up Google OAuth:

1. Go to the Google Cloud Console > APIs & Services > Credentials > Create OAuth client ID
2. Set the Authorized redirect URI to https://ocore.example.com/api/auth/oauth/google/callback
3. Copy the Client ID and Client Secret to your .env file

WebAuthn / Passkeys

WebAuthn enables passkey and hardware security key authentication. Both WEBAUTHN_RP_ID and WEBAUTHN_RP_ORIGIN must match the domain users access the dashboard from.

Web Push / VAPID

Web Push notifications are optional. Generate VAPID keys with:

npx web-push generate-vapid-keys

SSH Gateway

The SSH gateway allows users to connect to Odoo instances via SSH through oCore. The host key is stored in a persistent volume so that clients do not see host key change warnings after container restarts.

OAuth 2.1 Authorization Server

In most deployments, OAUTH_ISSUER does not need to be set because APP_URL is used by default. Set it only when the OAuth authorization server is exposed on a different URL than the dashboard.

Application

Frontend

These variables are set at build time as Docker build args. They are embedded into the Next.js bundle and cannot be changed at runtime.

Documentation Site

These variables are used by the oCore documentation site (Next.js, separate from the main frontend):

See the Frontend Configuration page for details on build-time vs runtime behavior.

Docker Compose Reference

Here is how each variable maps to the production Docker Compose file:

services:
  backend:
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER:-ocore}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-ocore}?sslmode=disable
      JWT_SECRET: ${JWT_SECRET}
      SSH_ENCRYPTION_KEY: ${SSH_ENCRYPTION_KEY}
      APP_URL: ${APP_URL}
      ENVIRONMENT: ${ENVIRONMENT:-production}
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_FROM: ${SMTP_FROM}
      SMTP_USERNAME: ${SMTP_USERNAME:-}
      SMTP_PASSWORD: ${SMTP_PASSWORD:-}
      OAUTH_GITHUB_CLIENT_ID: ${OAUTH_GITHUB_CLIENT_ID:-}
      OAUTH_GITHUB_CLIENT_SECRET: ${OAUTH_GITHUB_CLIENT_SECRET:-}
      OAUTH_GOOGLE_CLIENT_ID: ${OAUTH_GOOGLE_CLIENT_ID:-}
      OAUTH_GOOGLE_CLIENT_SECRET: ${OAUTH_GOOGLE_CLIENT_SECRET:-}
      WEBAUTHN_RP_ID: ${WEBAUTHN_RP_ID:-}
      WEBAUTHN_RP_ORIGIN: ${WEBAUTHN_RP_ORIGIN:-}
      VAPID_CONTACT: ${VAPID_CONTACT:-}
      VAPID_PUBLIC_KEY: ${VAPID_PUBLIC_KEY:-}
      VAPID_PRIVATE_KEY: ${VAPID_PRIVATE_KEY:-}
      SSH_GATEWAY_ENABLED: ${SSH_GATEWAY_ENABLED:-true}
      SSH_HOST_KEY_PATH: /app/data/ssh_host_ed25519_key
      SSH_LISTEN_ADDR: ${SSH_LISTEN_ADDR:-:2222}

  frontend:
    build:
      args:
        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL}
        NEXT_PUBLIC_SSH_PORT: ${NEXT_PUBLIC_SSH_PORT:-2222}

All variables with :- syntax have default values and are optional. Variables without defaults are required or conditionally required.

Validation Rules

The backend validates configuration at startup. If validation fails, the server exits with a descriptive error message.