Single-container deployment — API serves the Expo Web bundle as static fallback #186

New issue

Closed

opened 2026-06-20 15:44:48 +00:00 by james · 0 comments

james commented

2026-06-20 15:44:48 +00:00

Owner

The API container also serves the Expo Web static bundle, so self-hosters still run one image. API routes are served from /api/*; everything else falls through to the static bundle, with SPA-style index.html fallback for client-side routes.

Scope

Multi-stage Dockerfile: build apps/api, build apps/client (web target), copy the static bundle into the API image.
Next.js static-file serving (or a thin middleware) returns apps/client/dist/index.html for any non-/api/* route that doesn't match a static asset.
Headers: long cache on hashed assets, no-cache on index.html.
Verify the PWA install prompt + service worker continue to work served this way.
Update README "Quickstart" if the run command changes.

Acceptance criteria

docker run carol exposes the API at /api/* and serves the Expo Web bundle for every other path.
PWA install prompt fires on supported browsers; offline shell loads.
Image size hasn't grown by more than ~20% vs. the pre-split image.
No new self-hoster env vars (README "Configuration" tables unchanged unless a real new var lands).

Out of scope

Native packaging (Android, Flatpak — separate tickets).
Reverse proxy guidance — already in README.

Composes with

Decommission Next.js UI, Expo client scaffolding.

Part of

#176

The API container also serves the Expo Web static bundle, so self-hosters still run one image. API routes are served from `/api/*`; everything else falls through to the static bundle, with SPA-style `index.html` fallback for client-side routes. ## Scope - Multi-stage Dockerfile: build `apps/api`, build `apps/client` (web target), copy the static bundle into the API image. - Next.js static-file serving (or a thin middleware) returns `apps/client/dist/index.html` for any non-`/api/*` route that doesn't match a static asset. - Headers: long cache on hashed assets, no-cache on `index.html`. - Verify the PWA install prompt + service worker continue to work served this way. - Update README "Quickstart" if the run command changes. ## Acceptance criteria - [ ] `docker run carol` exposes the API at `/api/*` and serves the Expo Web bundle for every other path. - [ ] PWA install prompt fires on supported browsers; offline shell loads. - [ ] Image size hasn't grown by more than ~20% vs. the pre-split image. - [ ] No new self-hoster env vars (README "Configuration" tables unchanged unless a real new var lands). ## Out of scope - Native packaging (Android, Flatpak — separate tickets). - Reverse proxy guidance — already in README. ## Composes with Decommission Next.js UI, Expo client scaffolding. ## Part of #176

james added the

area:ci

area:service

feature

labels

2026-06-20 15:45:27 +00:00

james referenced this issue

2026-06-21 05:46:51 +00:00

feat(client): scaffold @carol/client — Expo Router + RN Web (#183) #198

james referenced this issue from a commit

2026-06-21 13:09:24 +00:00

feat(api): catch-all to serve the Expo Web bundle (#186)