|
| 1 | +# Task 003: Run nginx under Supervisord; wire startup port/docroot/pool overrides |
| 2 | + |
| 3 | +**Status**: completed |
| 4 | +**Depends on**: 001, 002 |
| 5 | +**Retry count**: 0 |
| 6 | + |
| 7 | +## Description |
| 8 | +Make nginx a managed Supervisord program and wire the runtime knobs into |
| 9 | +`scripts/start-services`: switch the nginx `listen` port to `8080` when Varnish is |
| 10 | +enabled, swap the docroot when `NGINX_DOCROOT` is set, and override the php-fpm pool |
| 11 | +`max_children` when `PHP_FPM_MAX_CHILDREN` is set. All rendering happens BEFORE |
| 12 | +supervisord launches (start-services line ~19) so daemons boot with the final config. |
| 13 | +Also fix the stale Varnish port echo. |
| 14 | + |
| 15 | +## Context |
| 16 | +- Related files: |
| 17 | + - `templates/supervisord/nginx.conf` (new: `program:nginx`, `command=nginx -g 'daemon off;'`, `autostart=true`, logs to stdout/stderr). The explicit `-g 'daemon off;'` here is the source of truth for foregrounding even if task 001 also set `daemon off;` in nginx.conf; passing it twice is harmless, but keep it on the supervisord command so the program never daemonizes out from under supervisord. |
| 18 | + - `Dockerfile` (add ONE explicit `COPY templates/supervisord/nginx.conf /etc/supervisor/conf.d/nginx.conf` line next to the existing per-file COPYs at lines ~48-52; the Dockerfile uses one explicit COPY per supervisord conf, NOT a glob, so add a matching explicit line) |
| 19 | + - `scripts/start-services` (render port/docroot/pool before launching supervisord; fix port echo) |
| 20 | +- Patterns to follow: |
| 21 | + - Existing supervisord program blocks under `templates/supervisord/` (e.g. `varnish.conf`, `php-fpm.conf`). |
| 22 | + - `start-services` already does pre-supervisord setup (MySQL init) before line 19; add the rendering there. |
| 23 | + - Varnish is `autostart=false` and started later; nginx on `8080` and Varnish on `80` do not overlap. |
| 24 | +- Notes: |
| 25 | + - All rendering must live in `scripts/start-services` BEFORE line 19 (the |
| 26 | + `supervisord -n` launch). This only takes effect when the container is started via |
| 27 | + `./start-services` (the CI flow and the README usage). The default `CMD |
| 28 | + ["/usr/bin/supervisord","-n"]` path does NOT run start-services, so nginx boots with |
| 29 | + its shipped defaults (`listen 80`, `root /data`) and `ENABLE_VARNISH`/overrides are |
| 30 | + only honored through start-services. This is acceptable: the defaults are the correct |
| 31 | + no-override behavior. Do NOT move rendering into a supervisord pre-hook. |
| 32 | + - Port switch: default config has `listen 80`. When `ENABLE_VARNISH=true`, `sed` it to |
| 33 | + `listen 8080` in `/etc/nginx/conf.d/default.conf` so Varnish (`-a :80`) fronts nginx. |
| 34 | + Anchor the sed (e.g. `s/listen 80;/listen 8080;/`) so it cannot also rewrite a `:80` |
| 35 | + inside a comment or fastcgi value. |
| 36 | + - Docroot override: when `NGINX_DOCROOT` is set, `sed` ONLY the `root` directive in |
| 37 | + `/etc/nginx/conf.d/default.conf` (task 001 sets `SCRIPT_FILENAME` from `$document_root`, |
| 38 | + so the single `root` rewrite is sufficient; do not touch the fastcgi block). |
| 39 | + Also `mkdir -p "$NGINX_DOCROOT"` so nginx does not 404/500 on a missing root. |
| 40 | + - Pool override: when `PHP_FPM_MAX_CHILDREN` is set, `sed` `pm.max_children` in the pool |
| 41 | + file via the glob `/etc/php/*/fpm/pool.d/zz-magento.conf` (avoids needing PHP_VERSION at |
| 42 | + runtime). The glob must run before supervisord starts php-fpm so the new value is read |
| 43 | + at boot (php-fpm reads the pool config once at start, not per request). |
| 44 | + - Fix: `scripts/start-services` currently echoes "Varnish is available on port 6081"; |
| 45 | + Varnish binds `:80`. Correct the message to reference port 80. |
| 46 | + - Override assertions are GUARDED by their env vars so they pass/skip in the default run |
| 47 | + and only execute in task 005's dedicated CI override step (mirrors the `ENABLE_VARNISH` guard |
| 48 | + already in `run-tests.sh`). |
| 49 | + - The `/data` mount is empty in CI. The HTTP-serving tests MUST first write a throwaway |
| 50 | + `index.php` (e.g. `<?php echo "nginx-ok";`) into the docroot being served |
| 51 | + (`/data` by default, `$NGINX_DOCROOT` when set) before curling, and assert the response |
| 52 | + body contains the sentinel string. For the custom-docroot test, `mkdir -p "$NGINX_DOCROOT"` |
| 53 | + first (the override CI step in task 005 may point it at a non-existent path). |
| 54 | + - nginx (`fastcgi_pass 127.0.0.1:9000`) connects to php-fpm per request, so nginx can boot |
| 55 | + before php-fpm is ready; but php-fpm itself is started by supervisord and start-services |
| 56 | + returns after the Elasticsearch loop without waiting for php-fpm/nginx. The serving |
| 57 | + assertions MUST retry the curl with a short bounded loop (a few attempts, 1s apart) to |
| 58 | + avoid a flaky failure against a php-fpm/nginx that is still coming up. Same applies to the |
| 59 | + Varnish-fronted curl on `:80` (start-services starts Varnish asynchronously via |
| 60 | + `supervisorctl start varnish`). |
| 61 | + |
| 62 | +## Requirements (Test Descriptions) |
| 63 | +These become assertions in `tests/run-tests.sh`. |
| 64 | + |
| 65 | +- [x] `it runs nginx as a supervisord-managed program` |
| 66 | +- [x] `it serves a php file from the document root over http on port 80 when varnish is disabled` |
| 67 | +- [x] `it serves php through varnish on port 80 with nginx listening on 8080 when varnish is enabled` |
| 68 | +- [x] `it serves from a custom document root when NGINX_DOCROOT is set` |
| 69 | +- [x] `it overrides php-fpm pm.max_children when PHP_FPM_MAX_CHILDREN is set` |
| 70 | +- [x] `it reports the correct varnish port in start-services output` |
| 71 | + |
| 72 | +## Acceptance Criteria |
| 73 | +- All requirements have passing assertions in `tests/run-tests.sh` |
| 74 | +- Default run (no Varnish): nginx serves php on `:80` |
| 75 | +- `ENABLE_VARNISH=true` run: nginx on `:8080`, Varnish serves php on `:80` |
| 76 | +- Override assertions are env-guarded and do not break the default and Varnish runs |
| 77 | +- Stale 6081 echo corrected |
| 78 | +- Code follows project standards (quoted shell, early returns, no em dashes) |
| 79 | + |
| 80 | +## Implementation Notes |
| 81 | +(Left blank - filled in by programmer during implementation) |
0 commit comments