41 lines
2.4 KiB
Markdown
41 lines
2.4 KiB
Markdown
## Context
|
|
|
|
The site is statically generated (Astro) and deployed behind nginx in Docker. Users can browse to `/videos`, `/podcast`, and `/about`, but direct navigation to these paths is currently resulting in a 404 in the deployed environment.
|
|
|
|
The static output contains directory-based pages (`/videos/index.html`, `/podcast/index.html`, `/about/index.html`). Some nginx configurations resolve directory indexes only for requests ending with `/` (e.g., `/videos/`) and may 404 for the no-trailing-slash path (`/videos`) unless explicitly handled.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Ensure `/videos`, `/podcast`, and `/about` resolve successfully (200) in the nginx/Docker deployment.
|
|
- Ensure requests to both the trailing slash and non-trailing slash forms work predictably.
|
|
- Keep behavior consistent with the SEO spec (indexable pages remain distinct; no SPA-style fallback masking real 404s).
|
|
|
|
**Non-Goals:**
|
|
- Changing site IA or page content.
|
|
- Introducing a client-side router fallback (SPA rewrite) that would hide missing pages.
|
|
|
|
## Decisions
|
|
|
|
### 1) Fix nginx static routing for directory index pages
|
|
|
|
**Decision:** Update nginx `try_files` to include `$uri/index.html` so requests like `/videos` resolve to `/videos/index.html` when present.
|
|
|
|
**Rationale:** This explicitly supports directory index pages without requiring a redirect, and prevents the common 404 case when the request does not include a trailing slash.
|
|
|
|
**Alternatives considered:**
|
|
- Redirect `/videos` -> `/videos/`: acceptable, but adds an extra hop and needs per-route rules or more complex logic.
|
|
- Rewrite all unknown paths to `/index.html`: not acceptable; would mask real 404s and break the semantics of distinct indexable pages.
|
|
|
|
### 2) Add a small verification step as part of deployment
|
|
|
|
**Decision:** Validate the deployed container serves `/videos`, `/podcast`, and `/about` as 200 in addition to verifying the build output includes the expected `index.html` files.
|
|
|
|
**Rationale:** This catches config regressions and ensures the fix applies to the real serving stack.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Path collisions] -> Using `$uri/index.html` could cause unexpected resolution if both a file and a directory exist. Mitigation: keep route structure simple and prefer one form.
|
|
- [Platform differences] -> Non-nginx deployments might still behave differently. Mitigation: document that the Docker/nginx deploy is canonical and ensure other hosts use equivalent rules.
|
|
|