Environment Variable Reference for Safe Online Exam

Safe Online Exam reads all of its runtime settings from process environment variables. The application does not load .env files itself — Compose explicitly supplies an environment file, and local development uses .env.example as a reference only. This page documents every variable the application accepts, the validation rules applied in hardened runtimes, and the deployment-template guidance that prevents misconfiguration.

Do not combine deployment templates blindly. Variables such as APP_IMAGE, PROJECT_ID, and PUBLIC_HOST are consumed by deployment scripts and Compose itself — they are not application runtime settings. Start from the single template that matches your topology: .env.example for a source checkout, .env.compose.example or .env.compose.secrets.example for Compose, or deploy/cloudrun.env.example for Cloud Run.

Profiles and Validation

The application resolves its runtime profile from the first non-empty value among APP_ENV, NODE_ENV, and the compatibility alias SPRING_PROFILES_ACTIVE.

Resolved value	Result
`prod` or `production`	Production profile and hardened validation.
`test`	Test profile; in-memory repositories are selected.
Any other value, or all values unset	Development profile.

Hardened validation is always active in production (APP_ENV=prod) and on any Cloud Run service regardless of profile — including an isolated APP_ENV=dev service. When hardened validation is active, the application performs strict checks on every database, Canvas, LTI, OAuth, secret, URL, and certificate value and terminates at startup before listening if any value is missing or unsafe. There is no partial startup.

The parser retains a small number of historical aliases — including APP_BASE_URL, CANVAS_BASE_URL, DEPLOYMENT_ID, and the DEV_*/PROD_* credential names — for maintained deployments. New installations should use only the canonical names documented here. In a hardened runtime, any supplied APP_BASE_URL or BASE_URL must exactly match TOOL_URL.

Critical Application Variables

string

required

Public HTTPS origin of this Safe Online Exam deployment. Must be an HTTPS origin with no path, query string, credentials, or fragment. This value is used in LTI launch verification, Canvas OAuth redirect validation, and SEB configuration generation.Example: https://seb-tool.example.edu

string

required

The HTTPS origin of the connected Canvas LMS installation. Must be an HTTPS origin only. Do not include a trailing slash or path segment. The application derives CANVAS_API_BASE_URL from this value when that variable is not explicitly set.Example: https://school.instructure.com

string

required

The client ID from the Canvas LTI 1.3 Developer Key created for this tool. This value must match the aud claim in LTI launch tokens issued by Canvas.Example: 170000000000042

string

required

Hostname, IP address, or Unix socket directory for the PostgreSQL server. Required in hardened runtimes. For Cloud SQL on Cloud Run, use the socket path format: /cloudsql/PROJECT:REGION:INSTANCE.Default: 127.0.0.1

string

required

Signing secret for Express session cookies. Must be at least 32 characters and must differ from STATE_ENCRYPTION_KEY. Rotating this value invalidates all active user sessions. Prefer the SESSION_SECRET_FILE alternative in production.

PostgreSQL Variables

PostgreSQL 17 or newer is the supported durable store. The application uses standard PostgreSQL protocol settings and is not tied to any managed provider.

Variable	Default	Notes
`DATABASE_HOST`	`127.0.0.1`	Hostname, IP, or Unix socket directory. Required in hardened runtimes.
`DATABASE_PORT`	`5432`	Integer from 1–65535. For Cloud SQL sockets this remains `5432`.
`DATABASE_NAME`	`canvas_seb`	Dedicated application database. Required in hardened runtimes.
`DATABASE_USER`	`canvas_seb`	Application database role. Required in hardened runtimes.
`DATABASE_PASSWORD`	Unset	Required in hardened runtimes. Prefer `DATABASE_PASSWORD_FILE`.
`DATABASE_PASSWORD_FILE`	Unset	Absolute path to a readable file containing the password. Conflicts with the direct variable.
`DATABASE_SSL_MODE`	`disable`	`disable`, `require`, `verify-ca`, or `verify-full`. Use `verify-full` over untrusted networks.
`DATABASE_POOL_MAX`	`5`	Per-process maximum connections, 1–100. Size the database for pool max multiplied by app instances and jobs.
`DATABASE_CONNECTION_TIMEOUT_MS`	`10000`	Connection acquisition timeout in milliseconds, 100–120000.
`DATABASE_STATEMENT_TIMEOUT_MS`	`30000`	Server-side statement timeout in milliseconds, 100–600000.
`DATABASE_CLEANUP_BATCH_SIZE`	`500`	Batch size for the cleanup job, 1–10000. Read by `db:cleanup` only, not normal startup.

A VM or external managed PostgreSQL connection should normally use verify-full with a trusted certificate chain. If the provider uses a private certificate authority, mount the CA file and set NODE_EXTRA_CA_CERTS to that path before process startup. Cloud Run uses an authenticated Unix socket that is local to the Cloud Run sandbox, so DATABASE_SSL_MODE=disable is correct in that topology.

Required Application Values

These variables are validated in every hardened runtime. Startup fails before the server begins listening if any required value is absent or fails its format check.

Variable	Purpose	Hardened requirement
`NODE_ENV`	Node runtime mode.	`production` for the deployed image.
`APP_ENV`	Application profile.	`dev` for isolated non-production; `prod` for production.
`PORT`	HTTP listener port.	Defaults to `8080`; platforms may inject it.
`TOOL_URL`	Public origin of this deployment.	HTTPS origin only, no path, query, or credentials.
`CANVAS_DOMAIN`	Connected Canvas origin.	HTTPS origin only.
`LTI_CLIENT_ID`	Canvas LTI 1.3 Developer Key client ID.	Required.
`LTI_PRIVATE_KEY`	RSA private JWK used for tool signing.	RSA 2048+ bits, exponent 65537, RS256-compatible.
`LTI_DEPLOYMENT_ID_CHECKING_ENABLED`	Enforce deployment-ID allowlist.	Defaults to `true`. Set `false` only for a controlled self-service course-install rollout.
`LTI_COURSE_NAVIGATION_VISIBLE_TO_STUDENTS`	Canvas placement visibility for students.	Only the case-insensitive value `false` selects `admins` visibility; any other value preserves `members`.
`LTI_DEPLOYMENT_ID`	Installed External App deployment ID.	Required when checking is enabled; comma/newline allowlist supported.
`CANVAS_API_CLIENT_ID`	Canvas API OAuth Developer Key client ID.	Required and distinct from the LTI key.
`CANVAS_API_CLIENT_SECRET`	Canvas API OAuth secret.	Required secret. Prefer `CANVAS_API_CLIENT_SECRET_FILE`.
`SESSION_SECRET`	Express session signing secret.	At least 32 characters; must differ from `STATE_ENCRYPTION_KEY`.
`STATE_ENCRYPTION_KEY`	AES-GCM material for opaque LTI/OAuth state.	At least 32 characters; must differ from `SESSION_SECRET`.
`OAUTH_TOKEN_ENCRYPTION_KEYRING`	JSON key-ID map for stored Canvas OAuth tokens.	Required secret; every value is a 32-byte base64url AES key.
`OAUTH_TOKEN_ENCRYPTION_ACTIVE_KEY_ID`	Key ID used for new token writes.	Required and must exist in the keyring.
`OAUTH_TOKEN_ENCRYPTION_MODE`	OAuth-token persistence rollout mode.	`enforce` for encrypted writes; `compat` is temporary rollback preparation only.
`SEB_CONFIG_ENCRYPTION_CERT_PEM`	X.509 certificate used to encrypt `.seb` output.	Required when certificate encryption is enabled.

Optional and Diagnostic Variables

Variable	Default	Notes
`SEB_QUIT_PASSWORD`	Unset	Optional managed exit-password fallback. Must be 8–128 characters with at least 5 different letters or numbers; common and predictable values are rejected.
`SEB_REQUIRED_DOMAINS`	Empty	Concrete reviewed hostnames only. Wildcards and identity-provider hosts are rejected. Accepts comma- or newline-separated values.
`SEB_CONFIG_ENCRYPTION_ENABLED`	`true`	Set explicitly to `false` to disable certificate wrapping. A teacher-set start password still wraps that assessment’s configuration.
`SEB_CONFIG_ENCRYPTION_CERT_PATH`	Unset	Path to the public certificate file; used by the Compose secret mount.
`SEB_CONFIG_ENCRYPTION_PUBLIC_KEY_PEM`	Unset	Local-development fallback public key; insufficient for hardened validation.
`SEB_CONFIG_ENCRYPTION_PUBLIC_KEY_PATH`	Unset	File path form of the local public-key fallback; insufficient for hardened validation.
`HOST`	`0.0.0.0`	TCP bind address.
`USE_IN_MEMORY_STORE`	`false`	Local and test use only; hardened runtimes reject `true`.
`APP_DEBUG_ENABLED`	`false`	Hardened runtimes reject `true`.
`APP_DETECTOR_DIAGNOSTICS_ENABLED`	`false`	Sanitized detector trace details. Production profile rejects `true`.
`APP_ASSET_VERSION`	Unset	Optional client cache-busting version string. `K_REVISION` is used when present on Cloud Run.
`DEV_TESTBED_ENABLED`	`false`	Enables bounded diagnostics on an isolated Cloud Run development instance. Allowed only with `APP_ENV=dev`; production rejects it.

File-Based Secrets

The following sensitive values each accept a mutually exclusive _FILE alternative that instructs the application to read the secret from a file path rather than a direct environment variable. Files are read once during configuration startup.

Direct variable	File alternative
`DATABASE_PASSWORD`	`DATABASE_PASSWORD_FILE`
`LTI_PRIVATE_KEY`	`LTI_PRIVATE_KEY_FILE`
`CANVAS_API_CLIENT_SECRET`	`CANVAS_API_CLIENT_SECRET_FILE`
`SESSION_SECRET`	`SESSION_SECRET_FILE`
`STATE_ENCRYPTION_KEY`	`STATE_ENCRYPTION_KEY_FILE`
`OAUTH_TOKEN_ENCRYPTION_KEYRING`	`OAUTH_TOKEN_ENCRYPTION_KEYRING_FILE`
`SEB_QUIT_PASSWORD`	`SEB_QUIT_PASSWORD_FILE`

The application rejects any configuration where both the direct variable and its _FILE alternative are set simultaneously. Unreadable paths are reported without echoing any secret contents. Required-value validation rejects a missing or empty file result just as it would a missing direct variable. Docker and Kubernetes secret mounts work without any provider-specific SDK. For detailed guidance on secret file format, keyring structure, the Docker Compose secrets profile, and rotation procedures, see Managing Secrets and File-Based Configuration.

Overview

Deployment

Configuration

User Workflows

Operations

Environment Variable Reference for Safe Online Exam

Profiles and Validation

Critical Application Variables

PostgreSQL Variables

Required Application Values

Optional and Diagnostic Variables

File-Based Secrets

​Profiles and Validation

​Critical Application Variables

​PostgreSQL Variables

​Required Application Values

​Optional and Diagnostic Variables

​File-Based Secrets

Profiles and Validation

Critical Application Variables

PostgreSQL Variables

Required Application Values

Optional and Diagnostic Variables

File-Based Secrets