.env.example

# valid values: development, test, staging, production
APP_ENV=development

##
# WebSocket Configuration
# In a local development environment, copy this file to .env.development
# Set WS_PORT to match the value in the Liturgical Calendar API project folder
# See: https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/blob/development/LitCalTestServer.php
##
WS_PROTOCOL=ws
WS_HOST=localhost
WS_PORT=8082

##
# API Configuration
# These variables define where the Unit Test Interface looks for the API
# (they do not control where the API actually runs)
##
API_PROTOCOL=http
API_HOST=localhost
API_PORT=8000
# API Base Path - the path prefix for all API endpoints
# Must match the API_BASE_PATH configured in the LiturgicalCalendarAPI .env
# In production, this is typically /api/dev/ or /api/v5/
# In local development, leave empty (API runs at root)
# Trailing slash is optional (the code normalizes either format)
API_BASE_PATH=

##
# API Proxy (optional)
#
# The API rate-limits unauthenticated callers by IP (UNAUTHENTICATED_RATE_LIMIT; 100/hour on the live
# deployment). One load of index.php spends five of those: /calendars twice (the page and the
# components-js ApiBase), plus /tests, /missals and /validations. That is 20 page loads per visitor
# per hour before the API starts answering 429.
#
# With API_PROXY_ENABLED=true the page fetches those four routes from api-proxy.php on this same
# origin instead, and that script attaches the project's first-party API key server-side. The key is
# never delivered to the browser, and the page stops consuming the public per-IP quota entirely.
#
# Off by default, and the flag gates api-proxy.php itself, not just whether the page uses it: while
# it is false the endpoint forwards nothing and never reads the API key, so an unenabled deployment
# is not quietly running an open relay on the project's key.
#
# It stays diagnosable while off, which is what you need before turning it on. The path form
# (api-proxy.php/calendars) requires the PHP SAPI to populate PATH_INFO -- components-js needs that
# form, because ApiBase appends /calendars to whatever base it is given -- so check it first:
#
#   curl -s https://your-host/api-proxy.php/calendars
#     {"title":"Proxy disabled","status":503,...,"route":"calendars"}   PATH_INFO works; safe to enable
#     {"title":"Unknown route","status":404,...,"Received: (none)"}     PATH_INFO absent; see below
#
# If PATH_INFO is absent the query form (api-proxy.php?route=calendars) still works for this app's own
# fetches, but components-js cannot use it -- raise that rather than enabling the flag.
#
# NOTE: this does not affect the checks themselves. Both runners still send the real API URLs to the
# WebSocket server as each check's sourceFile, because Health resolves a check's JSON schema by
# matching that URL against the API's configured host. The WS server has its own key (WS_API_KEY, set
# in the API's environment, not here).
##
API_PROXY_ENABLED=false

# The first-party API key the proxy attaches. Server-side only - never exposed to the browser.
# Leave empty to proxy without a key (the requests then still count against the per-IP quota, so this
# is only useful for local development where the limit is generous).
LITCAL_API_KEY=

##
# Where THIS SERVER reaches the API, when that is not where the browser reaches it.
#
# API_PROTOCOL / API_HOST / API_PORT above describe the API as the *browser* addresses it: they are
# handed to the page and used to build client-side URLs. Everything this app fetches server-side --
# api-proxy.php, and admin.php's components bootstrap -- needs an address reachable from the server
# process, and in a containerized deployment those are different: 'localhost' inside a container is
# the container, not the API.
#
# Set this to the internal base URL in that case (the docker stack sets it to http://litcal-api:8000
# on this service). Leave it empty for any single-host deployment, including production, where the
# two addresses are the same and the composed API_HOST form is used unchanged.
#
# Read as a COMPLETE base URL: scheme and host only, with an optional port and path. Any path it
# carries is the base path, so API_BASE_PATH does not apply to it. Credentials, query strings and
# fragments are refused rather than ignored -- this value decides where LITCAL_API_KEY is sent.
##
API_INTERNAL_URL=

# LitCal Frontend URL - the main LiturgicalCalendar project website
LITCAL_FRONTEND_URL=http://localhost:3000

##
# JWT Configuration
# Must match the API's JWT settings for server-side auth verification
# Generate a secure secret: php -r "echo bin2hex(random_bytes(32));"
##
JWT_SECRET=change-this-to-match-api-jwt-secret
JWT_ALGORITHM=HS256

##
# Playwright E2E Test Configuration
# These credentials are used by e2e tests to authenticate with the API
# They should match a valid user in your API's authentication system
##
TEST_USERNAME=
TEST_PASSWORD=
FRONTEND_URL=http://localhost:3003

##
# Zitadel OIDC. With both ZITADEL_ISSUER and ZITADEL_CLIENT_ID set, the navbar's Login button enters the
# OIDC flow; with either missing it falls back to the legacy username/password modal.
#
# ZITADEL_CLIENT_ID must be the "LiturgicalCalendar Tests" client, NOT the Frontend's: Zitadel rejects a
# redirect_uri that is not registered against the client making the request, and this app's callback is
# on its own port. `scripts/setup-zitadel.sh --update-env` in LiturgicalCalendarAPI writes the right one.
#
# ZITADEL_INTERNAL_URL is how this app reaches Zitadel for back-channel calls (discovery, token exchange,
# signing keys). Required wherever the two run in containers: ZITADEL_ISSUER is the BROWSER's address, and
# its "localhost" inside a container is the container itself.
#
# ZITADEL_PROJECT_ID is optional and only widens the accepted audience, matching the API's middleware.
#
# ZITADEL_ORG_ID is STRONGLY RECOMMENDED on a shared Zitadel instance. It appends the
# `urn:zitadel:iam:org:id:<id>` scope, forcing both sign-in AND new-user registration into that org.
# Without it Zitadel's hosted login lands a registration in its IAM-internal default org, and the user
# comes back with no email on file, their user id shown as their username, no roles, and invisible to
# org-scoped admin APIs — which looks like a broken session rather than a missing scope. Must be numeric;
# a non-numeric value is ignored with a log line rather than sent as a malformed scope.
##
# ZITADEL_ISSUER=http://localhost:8080
# ZITADEL_CLIENT_ID=
# ZITADEL_INTERNAL_URL=http://zitadel:8080
# ZITADEL_PROJECT_ID=
# ZITADEL_ORG_ID=

##
# API_INTERNAL_URL is the server-side address of the API, used by JwtAuth for its /auth/me fallback and by
# api-proxy.php. Without it both compose the browser-facing API_PROTOCOL/API_HOST/API_PORT, which is
# correct on a single host and wrong in containers.
##
# API_INTERNAL_URL=http://litcal-api:8000