Repository navigation
Added a static nginx maintenance page switched on by 'VORTEX_NGINX_MAINTENANCE_MODE'. - #3225
Merged
Merged
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info
WalkthroughThis change adds an Nginx static maintenance page that returns HTTP 503 when ChangesStatic maintenance mode
Priority: ⬇️ Low Estimated code review effort: 3 (Moderate) | ~25 minutes Change: Feature Sequence Diagram(s)sequenceDiagram
participant Client
participant Nginx
participant MaintenanceHTML
participant PHP
Client->>Nginx: Send web request
alt Maintenance mode is 1
Nginx->>MaintenanceHTML: Resolve internal maintenance URI
Nginx-->>Client: Return HTTP 503 and maintenance page
else Maintenance mode is disabled
Nginx->>PHP: Forward request
PHP-->>Nginx: Return application response
Nginx-->>Client: Return response
end
Merge Risk: ⚪ Minimal · up to
|
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Docstring Coverage |  |
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 4 files. (14 skipped: 1… | Write docstrings for the functions missing them to satisfy the coverage threshold. |
-
Check name Status Explanation Description Check Check skipped - CodeRabbit’s high-level summary is enabled. Title check The title clearly and concisely describes the main change: a static Nginx maintenance page controlled by VORTEX_NGINX_MAINTENANCE_MODE. Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 4 files. (14 skipped: 14 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
✨ Finishing Touches: 💡 2
-
📝 Generate docstrings: 💡
-
- Commit to this branch
- Create a new PR
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
🛠️ Fix failing CI checks: 💡
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
A rabbit checks the server light,
Nginx serves a page of white.
The waiting requests pause at the door,
While PHP is asked no more.
When maintenance signs depart,
Web replies resume their part.
Comment @coderabbitai help to get the list of available commands.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
1 similar comment
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
1 similar comment
This comment has been minimized.
This comment has been minimized.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3225 +/- ##
==========================================
- Coverage 92.29% 92.09% -0.20%
==========================================
Files 113 105 -8
Lines 5099 4933 -166
Branches 49 3 -46
==========================================
- Hits 4706 4543 -163
+ Misses 393 390 -3 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Code coverage (threshold: 90%) Per-class coverage |
Member
Author
|
Code coverage (threshold: 90%) Per-class coverage |
|
📖 Documentation preview for this pull request has been deployed to Netlify: https://6ad89be9fecbe803db122e2f--vortex-docs.netlify.app This preview is rebuilt on every commit and is not the production documentation site. |
AlexSkrypnyk
added
the
Needs review
This was referenced Oct 26, 2026
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
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
Setting
VORTEX_NGINX_MAINTENANCE_MODE=1on an environment now makes thenginxcontainer answer every request with HTTP 503 and the static page in.docker/config/nginx/maintenance.html. The check lives in/etc/nginx/conf.d/drupal/server_prepend-maintenance.confand runs in nginx's server rewrite phase, so it fires before the redirects map, theindex.phprewrite and everylocation, and no request reaches PHP-FPM.Until now the only way to keep visitors out was Drupal's own maintenance mode (
drush maint:set 1, orVORTEX_PROVISION_USE_MAINTENANCE_MODEduring provisioning), which runs in PHP and needs a working codebase and database. That's no help when Drupal itself has to stay down: a database migration on Lagoon, a release that broke bootstrap, or an incident where nobody should touch the site.With the variable unset, which is the default, nginx serves the site exactly as before. On Lagoon the switch is a runtime variable plus a redeploy, because the image entrypoint writes the value into the config when the container starts, and locally it's
VORTEX_NGINX_MAINTENANCE_MODE=1 ahoy up nginx. Drupal's maintenance mode, Lagoon's pod probes on port 50000 (/nginx_status) and the installer prompts are untouched.Before / After
Changes
nginx config and page
.docker/config/nginx/maintenance.conf(new):set $vortex_maintenance "${VORTEX_NGINX_MAINTENANCE_MODE:-0}", which the Lagoon entrypoint's envplate pass fills in at container start, then a server-levelifthat returns 503 when the value is exactly1, anderror_page 503 /__maintenance.htmlserved from aninternalexact-match location. The page URI is exempt from the check because nginx runs the server rewrite phase again for the error-page redirect.405 Not Allowedfrom the static file handler..docker/config/nginx/maintenance.html(new): a self-contained page with inline CSS, light and dark color schemes, and the installer'sYOURSITEtoken, so scaffolded sites show their own name..docker/nginx-drupal.dockerfile: copies the config to/etc/nginx/conf.d/drupal/server_prepend-maintenance.confand the page to/etc/nginx/html/maintenance.html. The entrypoint's envplate pass doesn't touch that directory, so${...}in a customized page survives.Local preview
docker-compose.yml: passesVORTEX_NGINX_MAINTENANCE_MODEto thenginxservice only. In the sharedx-environmentanchor it would change thecliandphpconfig too, andahoy up nginxwould recreate them as well.Tests
SubtestAhoyTrait::subtestAhoyNginxMaintenance(), called fromAhoyWorkflowTest::testAhoyWorkflowStateless()right after the Fast 404 subtest. It checks the homepage is Drupal, recreatesnginxwith the variable, runsnginx -t, and asserts 503 plus the page for/, a form POST and a core static file. It then stopsphpand asserts the page still comes back, and finally recreatesnginxwithout the variable and asserts Drupal is back, since the later doctor subtest only accepts 200 or 403.SutTrait::assertVortexFilesPresent(): asserts both new files ship with every installation.docker-compose.yml,nginx-drupal.dockerfileor the Lagoon block ofdocs/deployment.md.uselagoon/nginx-drupal:26.9.0directly: HEAD, PUT, DELETE and OPTIONS, an empty value andtrue, Lagoon basic auth, the PHP-routed/.lagoonhealthz(NGINX_FASTCGI_PASS=127.0.0.1), conditional requests against the page's ETag, and the probe port.Docs
hosting/lagoon.mdx: new "Serve a maintenance page" section under routine operations, covering turning it on and off with the Lagoon CLI, confirming withcurl, what it covers, and how to customize and preview the page.development/provision.mdx: 1 paragraph telling Drupal's maintenance mode and the nginx page apart, with a link.development/environment/docker.mdx: notes thenginxpass-through next to the anchor's variable list.lagoon.variables.shstub plus the regeneratedvariables.mdxrow, andlagoonhealthzadded tocspell.json.docs/deployment.md(Lagoon block): a short "Maintenance page" note that points at the docs.Decisions worth a look
1switches it on. Unset, empty,0andtrueall leave the site online, in line with the other Vortex flags./.lagoonhealthz. On Lagoon that endpoint goes to PHP, while the readiness and liveness probes hit/nginx_statuson port 50000, which aserver_prependinclude doesn't touch.Retry-AfterorCache-Controlheaders. Anyadd_headerin the page location would drop the inheritedX-LAGOONheader, and browsers, Varnish, Fastly and Cloudflare don't cache a 503 by default. Projects can add them to their copy of the file.nginxcontainer runs locally for all of them and the config is inert until switched on, so local preview and other container hosting get it too. The how-to lives on the Lagoon page.BASIC_AUTH_USERNAMEandBASIC_AUTH_PASSWORDset, visitors get the 401 prompt and then the page. Shield runs in Drupal, so the page is public on Shield-protected environments.Screenshots
The page as a scaffolded site renders it, with
YOURSITEreplaced by the project name.Summary by CodeRabbit
New Features
Documentation
Tests