Environment Variables Reference

This page provides a complete reference for all environment variables used to configure your Legend instance. Environment variables control everything from database connections to security settings, and are typically set in your docker-compose.yml file or .env file.

Required Environment Variables

These variables must be set for Legend to function:

LEGEND_SESSION_SECRET

Required: Yes
Default: None
Example: LEGEND_SESSION_SECRET=your-64-character-hex-string-here

A 64-character hexadecimal string used to encrypt session cookies and JWT tokens. This is a critical security setting that must be unique for each Legend instance.

How to generate:

openssl rand -hex 32

Security considerations:

Never share this value publicly
Never commit it to version control
Use a different value for each environment (development, staging, production)
Rotate periodically for enhanced security

Optional Environment Variables

These variables have sensible defaults and can be customized as needed:

LEGEND_DATA_DIR

Required: No
Default: /app/data
Example: LEGEND_DATA_DIR=/var/lib/legend/data

The directory where Legend stores all persistent data, including:

Entity catalog (YAML files)
Documentation files
Branding assets
Database backups

When to customize:

You want to store data on a specific volume or mount point
You’re using separate storage for the catalog and database
You need to integrate with an existing backup strategy

Directory structure:

LEGEND_DATA_DIR/
├── catalog/
├── docs/
├── branding/
└── backups/

LEGEND_DB_DIR

Required: No
Default: /app/data
Example: LEGEND_DB_DIR=/var/lib/legend/db

The directory where Legend stores the SQLite database file. By default, this is the same as LEGEND_DATA_DIR, but you can separate them for performance or organizational reasons.

When to customize:

You want the database on a faster storage medium (SSD)
You’re using separate storage for the catalog and database
You need different backup strategies for the database vs. catalog

Performance tip: SQLite performs best on local SSD storage. If your catalog is on network storage (NFS, SMB), consider keeping the database on local storage for better performance.

LEGEND_DB_FILENAME

Required: No
Default: legend.db
Example: LEGEND_DB_FILENAME=legend-production.db

The filename for the SQLite database file. This file is created in the LEGEND_DB_DIR directory.

When to customize:

You’re running multiple Legend instances in the same directory
You need to distinguish between different environments
You’re migrating from an existing database with a different name

LEGEND_PUBLIC_APP_URL

Required: No
Default: http://localhost:3000
Example: LEGEND_PUBLIC_APP_URL=https://legend.example.com

The public URL where users access your Legend instance. This is used for:

Generating links in emails
OIDC redirect URIs
API documentation
CORS configuration

When to customize:

You’re using a custom domain
You’re running Legend behind a reverse proxy
You’re using HTTPS (recommended for production)

Important:

Include the protocol (http:// or https://)
Do not include a trailing slash
Must match the URL users see in their browser

LEGEND_PUBLIC_ENABLE_BACKUPS

Required: No
Default: true
Example: LEGEND_PUBLIC_ENABLE_BACKUPS=false

Whether automatic daily backups are enabled. When enabled, Legend creates a database backup every day at 2:00 AM local time.

Options:

true: Automatic backups enabled (recommended)
false: Automatic backups disabled

When to disable:

You have an external backup solution
You want to control backup timing manually
You’re running in a resource-constrained environment

LEGEND_BACKUP_MAX_AGE_DAYS

Required: No
Default: 30
Example: LEGEND_BACKUP_MAX_AGE_DAYS=90

The maximum age (in days) for backup files. Backups older than this are automatically deleted.

When to customize:

You need longer retention for compliance requirements
You want to reduce storage usage
You have limited disk space

Considerations:

Longer retention uses more disk space
Each backup is a complete database snapshot
Balance retention needs with storage capacity

LEGEND_BACKUP_MIN_BACKUPS

Required: No
Default: 3
Example: LEGEND_BACKUP_MIN_BACKUPS=7

The minimum number of backup files to retain, regardless of age. This ensures you always have at least this many backups available for recovery.

When to customize:

You want more recovery options
You have ample storage space
You need to comply with retention policies

LEGEND_BACKUP_MAX_BACKUPS

Required: No
Default: 100
Example: LEGEND_BACKUP_MAX_BACKUPS=50

The maximum number of backup files to retain. When this limit is reached, the oldest backup is deleted.

When to customize:

You have limited disk space
You want to control storage usage
You need to comply with storage policies

LEGEND_LICENSE_SERVER_URL

Required: No
Default: https://mylegend.io
Example: LEGEND_LICENSE_SERVER_URL=https://license.internal.example.com

The URL of the license server for heartbeat and validation. Only change this if you’re using a custom license server or internal mirror.

When to customize:

You’re running an internal license server
You need to route traffic through a proxy
You’re testing with a staging license server

LEGEND_UPDATE_AGENT_IMAGE

Required: No
Default: legendapp/legend-update-agent:latest
Example: LEGEND_UPDATE_AGENT_IMAGE=registry.internal.example.com/legend-update-agent:latest

The Docker image reference for the self-hosted update agent, read by the install script when generating docker-compose.update-agent.yml. The update agent is a small companion container that powers the in-app Check for Updates button in the Admin panel.

When to customize:

You mirror container images in an internal registry (air-gapped or offline environments)
You’re testing a custom update agent build

Note: This variable is consumed by install-legend.sh, not by the Legend application container itself.

LEGEND_UPDATE_IMAGE (update agent container)

Required: No
Default: legendapp/legend:latest
Example: LEGEND_UPDATE_IMAGE=legendapp/legend:2026.08.1

The image reference the update agent should pull and deploy when updating the Legend container. This is set on the legend-update-agent container (the install script sets it from the Legend image). Change it only if you pin specific versions or mirror images.

When to customize:

You want the update agent to target a pinned release instead of latest
You mirror images in an internal registry

LEGEND_LOG_LEVEL

Required: No
Default: info
Example: LEGEND_LOG_LEVEL=debug

The logging level for the Legend application. Controls the verbosity of logs written to stdout.

Options:

error: Only error messages
warn: Warnings and errors
info: Informational messages, warnings, and errors (default)
debug: Debug messages and all above
trace: Trace messages and all above (very verbose)

When to customize:

Troubleshooting issues (use debug or trace)
Reducing log volume (use warn or error)
Compliance requirements for log retention

LEGEND_RATE_LIMIT_REQUESTS

Required: No
Default: 100
Example: LEGEND_RATE_LIMIT_REQUESTS=200

The maximum number of API requests per minute per IP address. This protects against abuse and denial-of-service attacks.

When to customize:

You have many concurrent users
You’re running automated scripts or integrations
You need to restrict access more aggressively

Considerations:

Higher limits allow more traffic but reduce protection
Lower limits provide better protection but may impact legitimate users
Monitor your actual usage before adjusting

LEGEND_RATE_LIMIT_WINDOW_MS

Required: No
Default: 60000
Example: LEGEND_RATE_LIMIT_WINDOW_MS=120000

The time window (in milliseconds) for rate limiting. The default is 60,000ms (1 minute).

When to customize:

You want to adjust the rate limiting window
You’re experiencing rate limit issues
You need to comply with specific rate limiting policies

LEGEND_CORS_ORIGINS

Required: No
Default: *
Example: LEGEND_CORS_ORIGINS=https://app.example.com,https://admin.example.com

Comma-separated list of allowed CORS origins. Controls which domains can make cross-origin requests to the Legend API.

When to customize:

You’re running Legend behind a reverse proxy
You have multiple subdomains accessing the API
You need to restrict API access for security

Security considerations:

* allows all origins (default, suitable for most deployments)
Specify exact origins for enhanced security
Include the protocol (https://) and no trailing slash

LEGEND_TRUST_PROXY

Required: No
Default: false
Example: LEGEND_TRUST_PROXY=true

Whether to trust reverse proxy headers (X-Forwarded-For, X-Forwarded-Proto). Enable this when running Legend behind a reverse proxy like nginx, Apache, or a load balancer.

Options:

true: Trust proxy headers
false: Ignore proxy headers (default)

When to enable:

Running behind nginx, Apache, or similar
Using a load balancer or CDN
Need accurate client IP addresses in logs

Security considerations:

Only enable if you trust the proxy
Malicious clients can spoof headers if not properly configured
Ensure your proxy is configured to set these headers correctly

Deprecated Environment Variables

These variables are deprecated and will be removed in a future version:

LEGEND_PUBLIC_DB_DIR

Deprecated: Use LEGEND_DB_DIR instead

This variable was renamed for consistency. The old name will continue to work but will be removed in a future release.

LEGEND_PUBLIC_DATA_DIR

Deprecated: Use LEGEND_DATA_DIR instead

This variable was renamed for consistency. The old name will continue to work but will be removed in a future release.

Environment Variable Examples

Minimal Configuration

LEGEND_SESSION_SECRET=your-64-character-hex-string-here

This is the only required variable. All other settings use their defaults.

Production Configuration

# Required
LEGEND_SESSION_SECRET=your-64-character-hex-string-here

# URLs
LEGEND_PUBLIC_APP_URL=https://legend.example.com

# Storage
LEGEND_DATA_DIR=/var/lib/legend/data
LEGEND_DB_DIR=/var/lib/legend/db

# Backups
LEGEND_PUBLIC_ENABLE_BACKUPS=true
LEGEND_BACKUP_MAX_AGE_DAYS=90
LEGEND_BACKUP_MIN_BACKUPS=7
LEGEND_BACKUP_MAX_BACKUPS=50

# Security
LEGEND_RATE_LIMIT_REQUESTS=200
LEGEND_CORS_ORIGINS=https://app.example.com,https://admin.example.com
LEGEND_TRUST_PROXY=true

# Logging
LEGEND_LOG_LEVEL=info

Air-Gapped Configuration

Customers who require air-gapped deployments may purchase that option with their license. Contact Legend support for air-gapped configuration details.

# Required
LEGEND_SESSION_SECRET=your-64-character-hex-string-here

# URLs
LEGEND_PUBLIC_APP_URL=https://legend.internal.example.com

# Storage
LEGEND_DATA_DIR=/var/lib/legend/data
LEGEND_DB_DIR=/var/lib/legend/db

# Backups
LEGEND_PUBLIC_ENABLE_BACKUPS=true

Development Configuration

# Required
LEGEND_SESSION_SECRET=dev-secret-not-for-production

# URLs
LEGEND_PUBLIC_APP_URL=http://localhost:3000

# Logging (verbose for debugging)
LEGEND_LOG_LEVEL=debug

# Rate limiting (relaxed for development)
LEGEND_RATE_LIMIT_REQUESTS=1000

Setting Environment Variables

Docker Compose

In your docker-compose.yml file:

services:
  legend:
    image: legendapp/legend:latest
    environment:
      - LEGEND_SESSION_SECRET=your-secret-here
      - LEGEND_PUBLIC_APP_URL=https://legend.example.com
      - LEGEND_DATA_DIR=/app/data
    volumes:
      - ./data:/app/data

Or using an .env file:

services:
  legend:
    image: legendapp/legend:latest
    env_file:
      - .env
    volumes:
      - ./data:/app/data

Docker Run

Using the -e flag:

docker run -d \
  --name legend \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e LEGEND_SESSION_SECRET=your-secret-here \
  -e LEGEND_PUBLIC_APP_URL=https://legend.example.com \
  legendapp/legend:latest

Or using an .env file:

docker run -d \
  --name legend \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  --env-file .env \
  legendapp/legend:latest

Troubleshooting

Legend won’t start:

Check that LEGEND_SESSION_SECRET is set
Verify the session secret is exactly 64 hexadecimal characters
Review container logs for configuration errors
Ensure all required directories exist and are writable

Session cookies not working:

Verify LEGEND_SESSION_SECRET is set correctly
Check that LEGEND_PUBLIC_APP_URL matches the URL users see
Ensure cookies are not blocked by browser settings
Verify the secret hasn’t changed (changing it invalidates all sessions)

Rate limiting issues:

Increase LEGEND_RATE_LIMIT_REQUESTS if legitimate users are blocked
Check logs for rate limit violations
Verify client IP addresses are correct (especially behind proxies)
Consider disabling rate limiting for trusted IP ranges

Backup issues:

Verify LEGEND_PUBLIC_ENABLE_BACKUPS is set to true
Check that the backup directory is writable
Ensure sufficient disk space is available
Review container logs for backup errors

License validation issues:

Verify outbound internet access is available to mylegend.io
Check that LEGEND_LICENSE_SERVER_URL is correct (if using a custom server)
Review container logs for license validation errors
Contact Legend support if you require an air-gapped deployment option

Best Practices

Security:

Always use a strong, random session secret
Never commit secrets to version control
Use different secrets for each environment
Rotate secrets periodically

Configuration:

Use .env files for environment-specific configuration
Document your configuration choices
Test configuration changes in staging before production
Keep configuration files in version control (excluding secrets)

Monitoring:

Monitor logs for configuration errors
Track rate limit violations
Review backup success/failure
Monitor license validation status

Maintenance:

Review and update configuration periodically
Remove deprecated variables
Test configuration changes before applying
Document any custom configuration

Next Steps

After configuring environment variables, proceed to Troubleshooting for help with common issues, or return to the Admin Guide Overview to explore other administrative features.