5402: Document and validate the operator-facing configuration surface#411
Merged
turegjorup merged 6 commits intoApr 29, 2026
Conversation
The image carries three distinct config surfaces:
- .env — Symfony app config (consumed via %env(...)% in config/)
- nginx env — runtime template substitution into nginx.conf
- php-fpm env — runtime tuning consumed by the itkdev/php8.4-fpm base
Annotate .env with per-variable descriptions so it is the canonical,
self-documenting Symfony example, and add dedicated production-example
files for the nginx and php-fpm runtime surfaces. Variable names mirror
what the image and templates actually consume — no APP_* prefix
translation.
Validated by the env-coverage check from the consolidation plan: every
%env(...)% reference in config/ is declared in .env and every
${VAR} in the nginx template is declared in the nginx example.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
scripts/check-env-coverage.sh validates the documentation surface
introduced in the previous commit:
1. Every %env(...)% read in config/ is declared in .env.
2. Every variable in .env, the nginx example, and the PHP example
has a preceding description.
3. Every ${VAR} in the nginx template is declared in the nginx
env.production.example.
4. Every PHP_* env set in the API Dockerfile's production stage is
declared in the PHP env.production.example.
Wired into the existing 'coding-standards:check' task and a dedicated
GitHub Actions workflow that runs on push to develop and on pull
requests, using the official go-task/setup-task action.
Also fills in five PHP_OPCACHE_* and PHP_PM_*_SPARE_SERVERS variable
descriptions that check (2) caught as missing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…r-mono-repo' into feature/5402-image-self-documenting # Conflicts: # CHANGELOG.md
Drop the dedicated nginx and PHP-FPM env.production.example files and the corresponding script checks. The operator-facing configuration contract for those two surfaces is documented adjacent to the image build (Dockerfile ENV blocks and the nginx template) rather than as duplicated example files. The .env / config/ coverage check remains: every %env(...)% read in config/ is declared in .env, and every variable in .env has a preceding description. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tuj
requested changes
Apr 29, 2026
| @@ -0,0 +1,51 @@ | |||
| # PHP-FPM runtime environment for the os2display api service image. | |||
| @@ -0,0 +1,23 @@ | |||
| # nginx runtime environment for the os2display nginx image. | |||
Co-authored-by: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com>
Co-authored-by: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com>
tuj
approved these changes
Apr 29, 2026
turegjorup
merged commit Apr 29, 2026
dc65882
into
feature/update-infrastructure-for-mono-repo
18 checks passed
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.envwith per-variable descriptions sourced from the docker-server-v3 example. Values and Symfony-Flex recipe blocks are unchanged; only comments are added. Withcomposer dump-env prodand.env.localoverrides on the operator host,.envitself is the canonical example for the Symfony app surface.The nginx and PHP-FPM runtime knobs are documented adjacent to the image build itself (Dockerfile
ENVblocks and the nginx template), so duplicated example files for those surfaces are out of scope here.Validation
scripts/check-env-coverage.shenforces two invariants:%env(...)%read inconfig/is declared in.env..envhas a preceding description comment.The script is wired into:
task coding-standards:env:check(and rolled up undertask coding-standards:check)..github/workflows/env_coverage.yamlthat runs onpush: developand on every PR, using the officialgo-task/setup-task@v2.Test plan
task coding-standards:env:checkexits 0 withPASS: env coverage OK.APP_ENV(or any other variable) makes the check fail with the offending variable name.%env(NEW_VAR)%reference inconfig/without declaringNEW_VAR=in.envmakes CI fail.Env coverageworkflow appears in the PR check list and passes on this PR.Commits
5402: Document the operator-facing configuration surface5402: Add CI check that enforces env coverage5402: Narrow scope to .env documentation only🤖 Generated with Claude Code