SSR/SSG Hybrid

[crutchcorn]

This PR adds in the SSR / SSG hybrid flag to support #1669

Summary by CodeRabbit

• New Features

  • Added SSR staging and branch preview deployments.
  • Production and automatic review previews now use static builds, while SSR previews can be deployed manually.
  • Added staging environment support with health checks and automatic machine management.

• Bug Fixes

  • Improved handling of missing, invalid, or mismatched localized content by showing localized 404 pages.
  • Corrected 404 responses so missing pages return the proper HTTP status.
  • Prevented errors when collections, events, authors, people, or posts are unavailable.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 58a004fe-df38-4aac-b22f-9a59f2438296

📥 Commits

Reviewing files that changed from the base of the PR and between 84b1992 and 2c8ee40.

📒 Files selected for processing (7)

• .github/workflows/fly-review.yml
• .github/workflows/fly-ssr-deploy.yml
• .github/workflows/fly-staging.yml
• .github/workflows/fly.yml
• CONTRIBUTING.code.md
• astro.config.ts
• fly.staging.toml

🚧 Files skipped from review as they are similar to previous changes (2)

• astro.config.ts
• .github/workflows/fly.yml

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The change adds static and SSR Docker runtimes, reusable Fly.io SSR deployment workflows, and staging configuration. It also standardizes localized 404 rewrites, validates missing content before rendering, and centralizes about-page path generation.

Changes

SSR deployment and route validation

Layer / File(s)	Summary
Selectable deployment outputs .github/workflows/*, Dockerfile, docker-compose.yml, fly.staging.toml, CONTRIBUTING.code.md, astro.config.ts	Docker and workflows now select static or server output. Fly.io supports reusable SSR staging and branch deployments with dedicated configuration.
Localized route and middleware handling src/middleware.ts, src/pages/404.astro, src/pages/[...locale]/*	Paraglide middleware now runs for all requests. Invalid locale routes rewrite to localized 404 paths, and 404 pages set the response status.
Content lookup validation src/pages/[slug].epub.ts, src/pages/collections/*, src/pages/events/book-club.astro	Missing, mismatched, hidden, or unavailable content now returns a 404 response or localized rewrite instead of using non-null assertions.
About-page path generation src/pages/[...locale]/about.astro, src/pages/sitemap-0.xml.ts, src/views/about/utils/route-data.ts	About-page path creation moves to shared route utilities. The sitemap uses the shared generator, which filters entries without page properties.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GitHubActions
  participant Dockerfile
  participant GHCR
  participant Flyio
  GitHubActions->>Dockerfile: Build with BUILD_OUTPUT=server
  Dockerfile->>GHCR: Push server image
  GitHubActions->>Flyio: Deploy image by digest
  Flyio-->>GitHubActions: Return HTTPS hostname

Loading

Merge Risk: ⚪ Minimal · up to 2c8ee

The deployment modes and localized route handling are ready to merge based on the reviewed changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	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 2 functions across 5 files. (6 skipped: 6 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding hybrid SSR/SSG deployment support with static previews and SSR staging or branch previews.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	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 2 functions across 5 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ssr-ssg-hybrid

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[fennifith]

Why rewrite instead of assert here? IMO if these custom pages stop working we'll want them to error.

[fennifith]

See discord comments - IMO this should only run on push to main. We should only need one staging app (total), not a new preview app for each branch/PR.