how-to-guide

Complete Guide to Logto Environment Variables: Core, CLI, and Frontend Configuration

June 30, 2026 logto-io/logto ↗

Logto environment variables control database connections, API endpoints, TLS certificates, feature flags, and third-party integrations across the core server, CLI utilities, and frontend applications.

The logto-io/logto repository relies on a comprehensive set of Logto environment variables to drive configuration across its monorepo architecture. These variables are read through process.env in Node.js contexts and injected into frontend builds via Vite, enabling deployment flexibility from local development to production Kubernetes clusters.

Core Server and Database Configuration

Database Connection (DB_URL)

The DB_URL variable is the most critical configuration, providing the PostgreSQL DSN for all core services. According to the source code in packages/shared/src/node/env/GlobalValues.ts at line 167, the system asserts this variable via assertEnv('DB_URL'), throwing if undefined.

// packages/shared/src/node/env/GlobalValues.ts#L167
const dbUrl = assertEnv('DB_URL'); // Required for core startup

Runtime Mode (NODE_ENV)

NODE_ENV determines production versus development behavior, affecting logging verbosity, security headers, and build optimization. The Jest setup file at packages/core/jest.setup.js (lines 12-14) normalizes this for testing, while packages/console/vite.config.ts (line 47) uses it to configure build targets.

API Endpoints (ENDPOINT and ADMIN_ENDPOINT)

ENDPOINT: Base URL for the user-facing API (https://<host>/)
ADMIN_ENDPOINT: Base URL for the administrative API

Both are defined in packages/core/jest.setup.js (lines 13-14) and utilized in CORS middleware tests at packages/core/src/middleware/koa-cors.test.ts (lines 58-104).

TLS Termination (HTTPS_CERT_PATH and HTTPS_KEY_PATH)

For HTTPS deployments, specify the certificate and private key paths:

// packages/shared/src/node/env/GlobalValues.ts#L71-L72
this.httpsCertPath = process.env.HTTPS_CERT_PATH;
this.httpsKeyPath = process.env.HTTPS_KEY_PATH;

Authentication and Security Settings

OIDC Private Keys (OIDC_PRIVATE_KEYS and OIDC_PRIVATE_KEY_PATHS)

During database seeding, these variables supply OpenID Connect private keys either as direct strings or file paths. The CLI command at packages/cli/src/commands/database/seed/oidc-config.ts (lines 90-91) processes these to establish initial identity provider configuration.

// packages/cli/src/commands/database/seed/oidc-config.ts#L90-L91
const privateKeys = process.env.OIDC_PRIVATE_KEYS;
const privateKeyPaths = process.env.OIDC_PRIVATE_KEY_PATHS;

Key Rotation Grace Period

PRIVATE_KEY_ROTATION_GRACE_PERIOD defines the overlap window when rotating OIDC keys, configured in packages/cli/src/commands/database/config.ts at line 209.

Username Case Sensitivity

Set CASE_SENSITIVE_USERNAME to toggle case-sensitive login handling, defined at line 285 of packages/shared/src/node/env/GlobalValues.ts.

Frontend Build and Feature Flags

Console and Experience Configuration

Frontend applications receive environment variables through Vite's define injection. The Console SPA configuration at packages/console/vite.config.ts (line 19) uses CONSOLE_PUBLIC_URL to set the public base path.

// packages/console/vite.config.ts#L19
base: process.env.CONSOLE_PUBLIC_URL || '/console/',

Experimental Features (DEV_FEATURES_ENABLED)

This feature-flag gate enables experimental functionality across packages:

Experience app: Checked in packages/experience/src/constants/env.ts (line 4)
Console build: Injected at packages/console/vite.config.ts (line 50)

Cloud-specific toggles like IS_CLOUD (line 47) and PROTECTED_APP_LOCAL_DEV (line 48) determine deployment-specific UI behaviors.

Third-Party Service Integrations

Analytics (PostHog and Application Insights)

PostHog configuration uses three variables defined in packages/shared/src/node/env/GlobalValues.ts (lines 211-213):

POSTHOG_PUBLIC_KEY
POSTHOG_PUBLIC_HOST
POSTHOG_PUBLIC_UI_HOST

These are injected into the Console bundle at packages/console/vite.config.ts (lines 55-58).

For Azure telemetry, APPLICATIONINSIGHTS_CONNECTION_STRING is read in packages/app-insights/src/node.ts (line 67) to conditionally initialize monitoring.

AI Translation (OpenAI)

The translation service configuration in packages/translate/src/openai.ts (lines 22-30) expects:

// packages/translate/src/openai.ts#L22-L30
apiKey: process.env.OPENAI_API_KEY,
model: process.env.OPENAI_MODEL_NAME ?? 'gpt-4.1',
proxyEndpoint: process.env.OPENAI_API_PROXY_ENDPOINT,

Search Services (Inkeep)

INKEEP_API_KEY enables optional search functionality, injected via Vite at packages/console/vite.config.ts (line 55).

Testing and CI/CD Variables

Integration Test Mode

INTEGRATION_TEST enables test-specific behaviors in the CLI toolkit, checked in packages/toolkit/core-kit/src/utils/integration-test.ts (line 3). Related test infrastructure includes:

WEBHOOK_HOST_FOR_APP: Mock webhook server hostname (packages/integration-tests/src/tests/api/hook/WebhookMockServer.ts, line 13)
MOCK_CONNECTOR_MESSAGE_DIR: Storage path for mock connector messages (packages/integration-tests/src/helpers/index.ts, line 53)

Schema Alteration Flags

Database migration scripts check CI (line 6 in alteration scripts like 1.18.0-add-agree-to-terms-policy.ts) and ALTERATION_TEST (line 8 in 1.9.0-keep-existing-password-policy.ts) to determine execution context.

Practical Configuration Examples

Minimal Local Development Environment

Create a .env file in your project root:


# Required: Core database connection

DB_URL=postgres://postgres:p0stgr3s@localhost:5432/logto

# API endpoints used by SDKs and tests

ENDPOINT=https://logto.test
ADMIN_ENDPOINT=https://logto.test/admin

# Feature flags

DEV_FEATURES_ENABLED=true
INTEGRATION_TEST=false

# Optional: TLS certificates for HTTPS

HTTPS_CERT_PATH=./certs/server.crt
HTTPS_KEY_PATH=./certs/server.key

# Optional: Analytics configuration

POSTHOG_PUBLIC_KEY=phc_your_key_here
POSTHOG_PUBLIC_HOST=app.posthog.com

# Optional: OpenAI for translation features

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL_NAME=gpt-4.1

Accessing Variables in Node.js Code

import { ConfigKey } from '@logto/shared';
import assert from 'assert';

// Example pattern from packages/cli/src/index.ts#L40
const databaseUrl = process.env[ConfigKey.DatabaseUrl];
assert(databaseUrl, 'DB_URL must be set');

Frontend Injection Pattern

Vite configurations inject variables as import.meta.env:

// packages/console/vite.config.ts#L47-L52
define: {
  'import.meta.env': {
    NODE_ENV: JSON.stringify(process.env.NODE_ENV),
    DEV_FEATURES_ENABLED: JSON.stringify(process.env.DEV_FEATURES_ENABLED),
    IS_CLOUD: JSON.stringify(process.env.IS_CLOUD),
  },
},

Key Source Files Reference

packages/shared/src/node/env/GlobalValues.ts: Central registry for core variables (DB_URL, TLS paths, PostHog, feature flags)
packages/core/jest.setup.js: Default environment setup for core test suites
packages/cli/src/commands/database/seed/oidc-config.ts: OIDC private key processing during initialization
packages/console/vite.config.ts: Frontend build-time variable injection
packages/app-insights/src/node.ts: Conditional Azure telemetry initialization
packages/translate/src/openai.ts: Third-party AI service configuration

Summary

Database connectivity requires DB_URL defined in packages/shared/src/node/env/GlobalValues.ts (line 167)
OIDC security relies on OIDC_PRIVATE_KEYS or OIDC_PRIVATE_KEY_PATHS during database seeding
Frontend builds receive variables via Vite injection in packages/console/vite.config.ts and packages/experience/vite.config.ts
Feature flags like DEV_FEATURES_ENABLED and IS_CLOUD control experimental and cloud-specific functionality
Testing modes use INTEGRATION_TEST, CI, and ALTERATION_TEST to modify behavior in test harnesses and migration scripts

Frequently Asked Questions

What is the required minimum set of Logto environment variables to start the server?

You must define DB_URL for the PostgreSQL connection. The core server asserts this variable at startup via assertEnv('DB_URL') in packages/shared/src/node/env/GlobalValues.ts. For HTTPS deployments, also provide HTTPS_CERT_PATH and HTTPS_KEY_PATH.

How do I configure Logto environment variables for HTTPS in production?

Set HTTPS_CERT_PATH and HTTPS_KEY_PATH to the absolute paths of your TLS certificate and private key files. The core server reads these in packages/shared/src/node/env/GlobalValues.ts (lines 71-72) to enable TLS termination.

Where are frontend-specific variables like DEV_FEATURES_ENABLED processed?

These are processed during the Vite build phase. packages/console/vite.config.ts (lines 47-50) injects DEV_FEATURES_ENABLED, NODE_ENV, and IS_CLOUD into the Console SPA, while packages/experience/src/constants/env.ts (line 4) checks the same flags for the Experience app.

Can I rotate OIDC private keys without downtime using environment variables?

Yes. Use PRIVATE_KEY_ROTATION_GRACE_PERIOD defined in packages/cli/src/commands/database/config.ts (line 209) to specify a grace period where both old and new keys remain valid. Provide new keys via OIDC_PRIVATE_KEYS or OIDC_PRIVATE_KEY_PATHS during the rotation window.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how logto-io/logto works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →