Merge remote-tracking branch 'origin/feature/update-infrastructure-for-mono-repo' into feature/5402-build-pipeline-ghcr

# Conflicts:
#	CHANGELOG.md

Author: turegjorup

.env

@@ -1,5 +1,8 @@
+# Docker Compose project name (used as a prefix for container names in local dev).
 COMPOSE_PROJECT_NAME=display
+# Hostname used by the local dev stack's reverse proxy.
 COMPOSE_DOMAIN=display.local.itkdev.dk
+# itkdev-docker template identifier.
 ITKDEV_TEMPLATE=symfony-6
 
 # In all environments, the following files are loaded if they exist,
@@ -18,12 +21,16 @@ ITKDEV_TEMPLATE=symfony-6
 # https://symfony.com/doc/current/best_practices.html#use-environment-variables-for-infrastructure-configuration
 
 ###> symfony/framework-bundle ###
+# Application environment (prod, dev, test). Override to 'prod' in .env.local on production hosts.
 APP_ENV=dev
+# Secret key used for encryption and security-related operations (MUST BE CHANGED in .env.local for production).
 APP_SECRET=CHANGE_ME
+# Comma-separated list of trusted proxy IPs for handling X-Forwarded headers.
 TRUSTED_PROXIES=127.0.0.1,REMOTE_ADDR
 ###< symfony/framework-bundle ###
 
 ###> doctrine/doctrine-bundle ###
+# Database connection string for MariaDB/MySQL.
 # Format described at https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
 # IMPORTANT: You MUST configure your server version, either here or in config/packages/doctrine.yaml
 #
@@ -33,105 +40,157 @@ DATABASE_URL="mysql://db:db@mariadb:3306/db?serverVersion=10.11.5-MariaDB"
 ###< doctrine/doctrine-bundle ###
 
 ###> nelmio/cors-bundle ###
-CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
+# Regular expression defining allowed origins for CORS requests.
 # Add allowed urls to .env.local as regex.
 # For development use:
 # CORS_ALLOW_ORIGIN="^.*"
+CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
 ###< nelmio/cors-bundle ###
 
 ###> lexik/jwt-authentication-bundle ###
+# Path to JWT private key file for signing tokens.
 JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
+# Path to JWT public key file for verifying tokens.
 JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
+# Passphrase for JWT private key (MUST BE CHANGED in .env.local for production).
 JWT_PASSPHRASE=CHANGE_ME
-# Default: 1 hour
+# Time-to-live in seconds for JWT access tokens. Default: 3600 (1 hour).
 JWT_TOKEN_TTL=3600
-# Default: 15 days
+# Time-to-live in seconds for screen JWT tokens. Default: 1296000 (15 days).
 JWT_SCREEN_TOKEN_TTL=1296000
 ###< lexik/jwt-authentication-bundle ###
 
 ###> gesdinet/jwt-refresh-token-bundle ###
-# Default: 2 hours
+# Time-to-live in seconds for JWT refresh tokens. Default: 7200 (2 hours).
 JWT_REFRESH_TOKEN_TTL=7200
-# Default: 30 days
+# Time-to-live in seconds for screen JWT refresh tokens. Default: 2592000 (30 days).
 JWT_SCREEN_REFRESH_TOKEN_TTL=2592000
 ###< gesdinet/jwt-refresh-token-bundle ###
 
 ###> redis ###
+# Prefix for Redis cache keys to avoid collisions across applications sharing a Redis instance.
 REDIS_CACHE_PREFIX=DisplayApiService
+# Connection string for Redis cache server.
 REDIS_CACHE_DSN=redis://redis:6379/0
 ###< redis ###
 
 ###> Http Client ###
+# Maximum time in seconds the HTTP client waits for a connection.
 HTTP_CLIENT_TIMEOUT=5
+# Maximum total duration in seconds for an HTTP request including transfer.
 HTTP_CLIENT_MAX_DURATION=30
+# Log level for outgoing HTTP requests (debug, info, notice, warning, error).
 HTTP_CLIENT_LOG_LEVEL=error
 ###< Http Client ###
 
 ###> App ###
+# Default date format for API responses (ISO 8601 with milliseconds).
 DEFAULT_DATE_FORMAT='Y-m-d\TH:i:s.v\Z'
+# Time interval for activation code expiration (ISO 8601 duration format, P2D = 2 days).
 ACTIVATION_CODE_EXPIRE_INTERVAL=P2D
+# Source for key vault configuration (ENVIRONMENT, FILE, etc.).
 KEY_VAULT_SOURCE=ENVIRONMENT
+# JSON configuration for key vault when using ENVIRONMENT source.
 KEY_VAULT_JSON="{}"
+# Enable tracking of screen information and statistics.
 TRACK_SCREEN_INFO=false
+# Interval in seconds between screen info updates.
 TRACK_SCREEN_INFO_UPDATE_INTERVAL_SECONDS=300
+# Toggle the relations checksum optimisation for content updates.
 RELATIONS_CHECKSUM_ENABLED=true
 ###< App ###
 
 ###> itk-dev/openid-connect-bundle ###
 # See docs/feed/openid-connect.md for variable explanations.
-# internal provider
+# internal provider (admin login)
+# URL to OIDC provider's metadata/discovery endpoint.
 INTERNAL_OIDC_METADATA_URL=INTERNAL_OIDC_METADATA_URL
+# Client ID registered with the OIDC provider.
 INTERNAL_OIDC_CLIENT_ID=INTERNAL_OIDC_CLIENT_ID
+# Client secret for authentication with the OIDC provider.
 INTERNAL_OIDC_CLIENT_SECRET=INTERNAL_OIDC_CLIENT_SECRET
+# Redirect URI for OIDC callback after authentication.
 INTERNAL_OIDC_REDIRECT_URI=INTERNAL_OIDC_REDIRECT_URI
+# Leeway time in seconds for token validation clock skew tolerance.
 INTERNAL_OIDC_LEEWAY=30
+# Name of the claim containing user's name.
 INTERNAL_OIDC_CLAIM_NAME=navn
+# Name of the claim containing user's email.
 INTERNAL_OIDC_CLAIM_EMAIL=email
+# Name of the claim containing user's group memberships.
 INTERNAL_OIDC_CLAIM_GROUPS=groups
 
-# external provider
+# external provider (citizen login)
+# URL to external OIDC provider's metadata/discovery endpoint.
 EXTERNAL_OIDC_METADATA_URL=EXTERNAL_OIDC_METADATA_URL
+# Client ID registered with the external OIDC provider.
 EXTERNAL_OIDC_CLIENT_ID=EXTERNAL_OIDC_CLIENT_ID
+# Client secret for authentication with the external OIDC provider.
 EXTERNAL_OIDC_CLIENT_SECRET=EXTERNAL_OIDC_CLIENT_SECRET
+# Redirect URI for external OIDC callback after authentication.
 EXTERNAL_OIDC_REDIRECT_URI=EXTERNAL_OIDC_REDIRECT_URI
+# Leeway time in seconds for external token validation clock skew tolerance.
 EXTERNAL_OIDC_LEEWAY=30
+# Salt used for hashing external OIDC user identifiers.
 EXTERNAL_OIDC_HASH_SALT=
+# Name of the claim containing user's sign-in identifier.
 EXTERNAL_OIDC_CLAIM_ID=signinname
 
-# cli redirect url
+# Redirect URI for CLI-based OIDC authentication flow.
 OIDC_CLI_REDIRECT=APP_CLI_REDIRECT_URI
 ###< itk-dev/openid-connect-bundle ###
 
 ###> Calendar Api Feed Source ###
 # See docs/feed/calendar-api-feed.md for variable explanations.
+# API endpoint for calendar location data.
 CALENDAR_API_FEED_SOURCE_LOCATION_ENDPOINT=
+# API endpoint for calendar resource data.
 CALENDAR_API_FEED_SOURCE_RESOURCE_ENDPOINT=
+# API endpoint for calendar event data.
 CALENDAR_API_FEED_SOURCE_EVENT_ENDPOINT=
+# JSON object for custom field mappings in calendar feeds.
 CALENDAR_API_FEED_SOURCE_CUSTOM_MAPPINGS='{}'
+# JSON object for modifying calendar event data.
 CALENDAR_API_FEED_SOURCE_EVENT_MODIFIERS='{}'
+# Date format used by the calendar API source.
 CALENDAR_API_FEED_SOURCE_DATE_FORMAT=
+# Timezone used by the calendar API source.
 CALENDAR_API_FEED_SOURCE_DATE_TIMEZONE=
+# Cache expiration time in seconds for calendar feed data.
 CALENDAR_API_FEED_SOURCE_CACHE_EXPIRE_SECONDS=300
 ###< Calendar Api Feed Source ###
 
 ###> Event Database Api V2 Feed Type ###
+# Cache expiration time in seconds for event database API v2 responses.
 EVENTDATABASE_API_V2_CACHE_EXPIRE_SECONDS=300
 ###< Event Database Api V2 Feed Type ###
 
 ###> Admin configuration ###
+# API key for Rejseplanen (Danish journey planner) integration.
 ADMIN_REJSEPLANEN_APIKEY=
+# Enable display of screen online/offline status in admin interface.
 ADMIN_SHOW_SCREEN_STATUS=false
+# Enable touch button regions feature in admin interface.
 ADMIN_TOUCH_BUTTON_REGIONS=false
+# JSON array defining available login methods for admin interface.
 ADMIN_LOGIN_METHODS='[{"type":"username-password","enabled":true,"provider":"username-password","label":""}]'
+# Enable enhanced preview mode with additional features.
 ADMIN_ENHANCED_PREVIEW=false
 ###< Admin configuration ###
 
 ###> Client configuration ###
+# Timeout in milliseconds for checking login status.
 CLIENT_LOGIN_CHECK_TIMEOUT=20000
+# Timeout in milliseconds before attempting to refresh authentication token. 300000 = 5 minutes.
 CLIENT_REFRESH_TOKEN_TIMEOUT=300000
+# Interval in milliseconds for checking release timestamp updates. 600000 = 10 minutes.
 CLIENT_RELEASE_TIMESTAMP_INTERVAL_TIMEOUT=600000
+# Interval in milliseconds for running content scheduling checks. 60000 = 1 minute.
 CLIENT_SCHEDULING_INTERVAL=60000
+# Interval in milliseconds for pulling new content from server. 90000 = 1.5 minutes.
 CLIENT_PULL_STRATEGY_INTERVAL=90000
+# JSON configuration for client color scheme with location coordinates.
 CLIENT_COLOR_SCHEME='{"type":"library","lat":56.0,"lng":10.0}'
+# Enable debug mode for client-side logging and diagnostics.
 CLIENT_DEBUG=false
 ###< Client configuration ###

.github/workflows/env_coverage.yaml

@@ -0,0 +1,23 @@
+---
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+
+name: Env coverage
+
+jobs:
+  env-coverage:
+    name: Validate env documentation coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install task
+        uses: go-task/setup-task@v2
+        with:
+          version: 3.x
+
+      - name: Run coding-standards:env:check
+        run: task coding-standards:env:check

CHANGELOG.md

@@ -37,6 +37,8 @@ All notable changes to this project will be documented in this file.
 - Added vitest for frontend unit tests.
 - Updated infrastructure and image build for mono-repo.
 - Fixed nginx static-file location to fall back to PHP so LiipImagineBundle can generate missing thumbnails (#370).
+- Annotated `.env` so it serves as the canonical, self-documenting Symfony
+  env example, with a CI check that enforces it stays in sync with `config/`.
 - Switched image build pipeline to GHCR with multi-arch layer caching.
 
 ### NB! Prior to 3.x the project was split into separate repositories

Taskfile.yml

@@ -108,6 +108,7 @@ tasks:
       - task coding-standards:php:check
       - task coding-standards:markdown:check
       - task coding-standards:yml:check
+      - task coding-standards:env:check
 
   coding-standards:apply:
     desc: "Apply coding standards."
@@ -128,6 +129,11 @@ tasks:
     cmds:
       - docker compose run --rm --volume "$PWD:/md" prettier '**/*.{yml,yaml}' --check
 
+  coding-standards:env:check:
+    desc: Validate that every Symfony env variable in config/ is documented in .env.
+    cmds:
+      - sh scripts/check-env-coverage.sh
+
   coding-standards:assets:apply:
     desc: Apply coding standards for assets
     cmds:

scripts/check-env-coverage.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+# Validate that .env documents every Symfony env variable consumed in config/:
+#   1. Every %env(...)% read in config/ is declared in .env.
+#   2. Every variable in .env has a preceding description comment.
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Vars consumed via %env() but intentionally not part of the .env contract
+# (e.g. injected by tooling, not Symfony-defined defaults).
+ALLOW_LIST="VAR_DUMPER_SERVER"
+
+failed=0
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+# Check 1 — every %env(...)% read in config/ is declared in .env
+grep -rhoE '%env\(([a-z]+:)*[A-Z_][A-Z0-9_]*\)%' config/ \
+  | sed -E 's/%env\(([a-z]+:)*([A-Z_][A-Z0-9_]*)\)%/\2/' \
+  | sort -u > "$tmp/symfony-reads"
+grep -E '^[A-Z_][A-Z0-9_]*=' .env | cut -d= -f1 | sort -u > "$tmp/env-declares"
+echo "$ALLOW_LIST" | tr ' ' '\n' | sort -u > "$tmp/allow"
+
+undocumented=$(comm -23 "$tmp/symfony-reads" "$tmp/env-declares" | comm -23 - "$tmp/allow")
+if [ -n "$undocumented" ]; then
+  echo "FAIL: %env(...)% reads in config/ not declared in .env:"
+  echo "$undocumented" | sed 's/^/  /'
+  failed=1
+fi
+
+# Check 2 — every variable in .env has a preceding description comment
+unannotated=$(awk '
+  # Order matters: ### must be tested before # so recipe markers are not
+  # treated as descriptions.
+  /^###/  { last_was_comment = 0; next }
+  /^#/    { last_was_comment = 1; next }
+  /^$/    { last_was_comment = 0; next }
+  /^[A-Z_][A-Z0-9_]*=/ {
+    name = $0; sub("=.*", "", name)
+    if (!last_was_comment) print name
+    last_was_comment = 0
+  }
+' .env)
+if [ -n "$unannotated" ]; then
+  echo "FAIL: variables in .env without preceding description:"
+  echo "$unannotated" | sed 's/^/  /'
+  failed=1
+fi
+
+if [ "$failed" -eq 0 ]; then
+  echo "PASS: env coverage OK"
+fi
+exit "$failed"