Environment Variables

Required and optional environment variables for local, mixed, and Docker deployments.

by @saifyxpro

HeadlessX uses a small set of hard requirements and a larger set of service-specific variables.

Main workspace file

Use the root workspace file as the main source of truth:

This drives the shared runtime for:

  • API
  • queue worker
  • yt-engine
  • HTML-to-Markdown service
  • shared web runtime values

Root example

Current local example:

Optional values are still common in some deployments:

  • INTERNAL_API_URL
  • FRONTEND_URL

Docker example

Full Docker uses:

Important Docker values:

Required core variables

VariablePurpose
DATABASE_URLPostgreSQL connection string
REDIS_URLRedis connection for BullMQ and crawl jobs
PORTbackend API port
WEB_PORTdashboard port
NEXT_PUBLIC_API_URLbrowser-facing backend URL for the dashboard
DASHBOARD_INTERNAL_API_KEYserver-side dashboard to API secret
CREDENTIAL_ENCRYPTION_KEYencryption key for stored secrets

Service URLs

VariablePurpose
HTML_TO_MARKDOWN_SERVICE_URLmarkdown extraction service
YT_ENGINE_URLYouTube engine base URL
YT_ENGINE_PORTlocal yt-engine port override
HTML_TO_MARKDOWN_PORTlocal markdown service port override

Search and integration keys

VariablePurpose
TAVILY_API_KEYTavily routes
EXA_API_KEYExa routes

Security values

Generate long random values for:

  • DASHBOARD_INTERNAL_API_KEY
  • CREDENTIAL_ENCRYPTION_KEY

Example:

Failure modes to know

  • missing REDIS_URL: queue-backed crawl features fail
  • missing YT_ENGINE_URL: YouTube endpoints fail
  • missing dashboard internal key: protected dashboard proxy flows break
  • mismatched NEXT_PUBLIC_API_URL and FRONTEND_URL: web-to-API communication issues

Troubleshooting