@clubedge/create-clubedge-app 0.41.1 → 0.42.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.42.0
+
+- **Mobile apps with Capacitor**: default to Starter `v0.27.0` (#138). `--framework vite --api hono --shell capacitor` (or `--api fastapi`) packages the Vite frontend as an Android and iOS app in `apps/shell` (#135):
+  - Template schema 5 adds the `shell` role: a stack that packages a frontend's static build and runs no server, so it has no Dockerfile or deployment, and `deploy` leaves it out. Older CLIs refuse a schema 5 Starter and ask for an update.
+  - `--shell` is refused with Next.js and TanStack Start, which render on their own server. Interactive runs ask about a mobile app only after a frontend and its API.
+  - `apps/shell/.env.local` is created from its example (`WEB_URL`, the website the app calls), and `add`, `remove`, and `upgrade` keep its values.
+  - A variant file's `clubedge:if` blocks are kept or dropped for the selection where the variant lands, like other conditional files'. Before, they stayed in the project.
+  - MCP: `get_starter_capabilities` lists each slot's question, and the tools describe what each role pairs with.
+  - CI generates a mobile project from the pinned Starter.
+- **Client addresses per platform** (#136, #137): `deploy` tells the app where each client's address is, for Starter `v0.27.0`'s rate limits:
+  - `CLIENT_IP_HEADER`: `x-real-ip` on Railway and Vercel, `cf-connecting-ip` on Render (from the Cloudflare edge in front of it), `fly-client-ip` on Fly.io, `x-nf-client-connection-ip` on Netlify.
+  - `TRUSTED_PROXY_HOPS=1` behind Caddy with Docker Compose, and on a frontend's API, which only the frontend's server reaches.
+  - Previews and `try` set them too, and the env file's settings replace both defaults.
+- **Docker Compose behind Caddy, with images on GHCR** (#136): `deploy` with the docker option now works for full-stack apps too, and writes:
+  - `compose.yaml`: each app's image (pulled from `IMAGE_PREFIX` at `TAG`, or built with `--build`), behind Caddy, the only service that publishes ports, with automatic HTTPS for `DOMAIN`.
+  - A `Caddyfile`.
+  - `.github/workflows/release-images.yml`: each published release builds every app for linux/amd64 and linux/arm64 and pushes it to the repository's container registry, tagged with the version, `<major>.<minor>`, and `latest`.
+  - Running `deploy` again writes only the files that are missing and never overwrites one you changed. A frontend and API's `compose.yaml` from an earlier deploy stops it until you move that file away.
+- `upgrade` keeps the blank line after a section the Starter adds to the local env file between two others (#138).
+
 ## 0.41.1
 
 - Default to Starter `v0.26.1` (#130): new projects' weekly upgrade workflow opens its pull request when the upgrade leaves conflict markers in a `package.json`, listing them, instead of stopping without one. It runs `upgrade --detailed-exit-code`, from 0.41.0. Existing projects get the workflow through their next upgrade pull request.

package/README.md

@@ -102,7 +102,7 @@ pnpm dev
 
 Or start it with npm: `npx @clubedge/create-clubedge-app my-app`. The generated project is a pnpm workspace, so dependencies are installed with pnpm either way; the CLI falls back to `corepack pnpm` when `pnpm` is not on your path. Without a destination, the CLI asks where to create the project.
 
-The generated project includes `apps/web/.env.local` (and `apps/api/.env.local` with a separate API), created from the example and pointing at the local services you chose. Its `SETUP.md` describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at `/dashboard`.
+The generated project includes `apps/web/.env.local` (and `apps/api/.env.local` with a separate API, `apps/shell/.env.local` with a mobile app), created from the example and pointing at the local services you chose. Its `SETUP.md` describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at `/dashboard`.
 
 The default Starter release ships inside the CLI package, so GitHub is only contacted when you pass `--ref`. Internet access is needed to install dependencies.
 
@@ -141,7 +141,22 @@ They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend c
 
 With `--auth supabase`, the Vite app owns the browser session and attaches its access token to contract requests. Hono or FastAPI verifies that token with Supabase Auth and returns the contract's shared user shape. Configure `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_URL`, and `SUPABASE_PUBLISHABLE_KEY` in the generated env examples; no Supabase service-role key goes to the browser.
 
-With the Hono API, the decoupled stacks support every module option the full-stack frameworks do (since Starter v0.26.1), each running in the API with the matching UI in the frontend; with FastAPI, they support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache. Both work with any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
+With the Hono API, the decoupled stacks support every module option the full-stack frameworks do (since Starter v0.27.0), each running in the API with the matching UI in the frontend; with FastAPI, they support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache. Both work with any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that runs the frontend and API as separate services behind Caddy, which serves the frontend over HTTPS while the API stays on the Compose network (see [Deploy with Docker Compose](#deploy-with-docker-compose)); copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production` and fill in their values. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
+
+### A mobile app
+
+Since CLI 0.42.0, with Starter v0.27.0, the Vite frontend can also be packaged as an Android and iOS app with [Capacitor](https://capacitorjs.com). Earlier Starters have no mobile shell, and the CLI refuses `--shell` with them.
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --framework vite --api hono --shell capacitor
+```
+
+| Flag                | App                                                       | Where        |
+| ------------------- | --------------------------------------------------------- | ------------ |
+| `--shell capacitor` | The Vite app, packaged for Android and iOS with Capacitor | `apps/shell` |
+| `--shell none`      | No mobile app (the default)                               |              |
+
+A shell packages the frontend's static files, so it needs `--framework vite`, and the frontend still needs its API (`--api hono` or `--api fastapi`). Next.js and TanStack Start render their pages on their own server, so they cannot be packaged: the CLI refuses `--shell` with them, and interactive runs only ask about a mobile app after a frontend and its API. The shell runs no server, so `deploy` deploys the frontend and the API as above and leaves it out.
 
 ## Choosing modules
 
@@ -156,7 +171,7 @@ Authentication, file storage, caching, email, payments, background jobs, observa
 | `--payments` | `stripe` (needs an auth module), `none` | `none` |
 | `--jobs` | `pg-boss`, `bullmq` (needs the `redis` cache), `inngest`, `none` | `none` |
 | `--observability` | `otel` (OpenTelemetry, to any OTLP collector), `sentry`, `none` | `none` |
-| `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
+| `--deploy`  | `docker` (any container host; `deploy` sets up Docker Compose with Caddy), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `neon` (a free hosted Neon database), `none` | `docker` |
 
 ```sh
@@ -181,6 +196,7 @@ Usage:
 Options:
   --framework <id>        App framework, such as next or tanstack-start (or vite, a frontend)
   --api <id>              A separate API for a frontend, such as hono or fastapi
+  --shell <id>            A mobile app that packages a frontend, such as capacitor
   --<module> <option>     A module option, such as --auth none; the Starter lists its modules
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                           (upgrade: the Starter to upgrade to)
@@ -207,7 +223,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.26.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.27.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -226,7 +242,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.26.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.27.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -234,7 +250,7 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 - Files you never changed are updated, added, or deleted.
 - Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve. The Starter's whole new version of each such file is saved in `.clubedge/incoming/` to compare with yours (`git diff --no-index <file> .clubedge/incoming/<file>`); Git ignores that folder, so delete it when you are done.
 - Your own files are never touched.
-- Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local` with a separate API) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
+- Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local` or `apps/shell/.env.local` when the project has them) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
 - `pnpm-lock.yaml` is replaced if you never changed your dependencies; otherwise `pnpm install` reconciles it.
 
 Several modules in one command are applied as one change, and their requirements are checked together, so `add auth supabase storage supabase` works even though Supabase Storage needs Supabase Auth. When lines conflict, the CLI lists each file with its number of conflict blocks. Before an upgrade, it lists the Starter releases it crosses with the sections of their release notes, such as `v0.13.0  Observability, Tests, Also`.
@@ -324,6 +340,30 @@ In a project with `--deploy netlify`, `pnpm clubedge deploy` uses [Netlify's CLI
 
 In a project with `--deploy render`, `pnpm clubedge deploy` uses Render's API. Render builds the Dockerfile from your Git repository, so push the project to GitHub, GitLab, or Bitbucket first, with Render's access to it granted in the dashboard; `deploy` warns about commits that aren't pushed. It signs in with an API key: `RENDER_API_KEY`, or else it opens the dashboard's API keys page and asks you to paste one. It creates or reuses a web service named after the package, on the Docker runtime and a starter instance (pre-deploy commands need a paid type), which runs `node /app/migrate.mjs` before each release, checks `/api/health`, and deploys again on each push, as `render.yaml` describes. `DATABASE_URL` comes from the env file (Render Postgres, Neon, Supabase, ...). It sets the production variables: the env file's values, the service's `*.onrender.com` URL, and a generated `BETTER_AUTH_SECRET` that later runs keep. Then it starts a deploy and waits until it is live. When Render names the app something other than `https://<service>.onrender.com`, `deploy` sets that URL and deploys again, since the build compiles it in. Running it again reuses the service. Render bills the instance on your plan.
 
+### Deploy with Docker Compose
+
+In a project with `--deploy docker` (the default), `pnpm clubedge deploy` prepares the project for a server of your own and creates nothing anywhere else. It writes three files to commit:
+
+- `compose.yaml` runs each app's image behind [Caddy](https://caddyserver.com), the only service that publishes ports (80, and 443 over TCP and UDP): it serves `DOMAIN` over HTTPS, with certificates it obtains and renews by itself. A full-stack app (Next.js or TanStack Start) is one service, `web`, built from the root `Dockerfile`; a frontend and its API are two, the frontend `web`, which Caddy serves, and `api`, which stays on the Compose network behind the frontend's `/api` proxy. Each service has an image, `${IMAGE_PREFIX:-<project>}-<service>:${TAG:-latest}`, and its build: `docker compose up -d` pulls the released images when `IMAGE_PREFIX` points at GitHub's registry, and `--build` builds them on the server. The public URL defaults to `https://$DOMAIN`: Next.js also gets it as a build argument, and Better Auth on a Vite frontend as `BETTER_AUTH_URL`.
+- `Caddyfile`: every request for `DOMAIN` goes to the public app.
+- `.github/workflows/release-images.yml`: each published GitHub release builds every app's image for `linux/amd64` and `linux/arm64` and pushes it to `ghcr.io/<owner>/<repository>-<service>`, tagged with its version (`1.2.3`), `1.2`, and `latest`; run by hand on the default branch, it pushes `edge`. It never runs for tag pushes, so a deleted tag leaves no images behind. The values an image compiles in come from repository variables: `NEXT_PUBLIC_APP_URL` for Next.js, the `VITE_*` values for a Vite frontend.
+
+Then point the domain's DNS A and AAAA records at the server, publish a release, and on the server, next to `compose.yaml`, the `Caddyfile`, and `.env.production` (the whole project to build there):
+
+```sh
+# .env.production: DOMAIN=example.com, the app's variables, and, to run the released images,
+# IMAGE_PREFIX=ghcr.io/<owner>/<repository> (TAG=1.2.3 pins a release; latest otherwise)
+docker login ghcr.io                             # while the packages are private: a token with read:packages
+docker compose --env-file .env.production run --rm web node /app/migrate.mjs   # api for a frontend and its API
+docker compose --env-file .env.production up -d  # --build builds the images on the server
+```
+
+`deploy` prints these steps, with the `IMAGE_PREFIX` of your repository when `origin` is on GitHub. To update, publish a release, then on the server `docker compose --env-file .env.production pull` (or set `TAG` to the new version), run the migrations, and `up -d` again. Running `deploy` again writes the files that are missing and never overwrites one: it keeps a `Caddyfile` or workflow you changed, and says so, and stops when `compose.yaml` differs from the one it writes, so move yours away to get the new one. Compose prefers `compose.yaml` to the Starter's `docker-compose.yml`, so run the local one by name: `docker compose -f docker-compose.yml up --build`, which `pnpm docker:dev` does since Starter v0.27.0.
+
+### Client addresses
+
+Rate limits and logs count each visitor by address, which the platform's proxies hide. `deploy` tells the public service where to find it: `CLIENT_IP_HEADER`, the header the platform's edge sets to the client's address, replacing any copy the client sent (`x-real-ip` on Railway and Vercel, `cf-connecting-ip` on Render, from the Cloudflare edge in front of it, `fly-client-ip` on Fly.io, `x-nf-client-connection-ip` on Netlify), or, with Docker Compose, `TRUSTED_PROXY_HOPS=1`: Caddy is the one proxy of your own that sets `X-Forwarded-For`, and the app reads the entry that many places from the right. A frontend's API, reached only through the frontend's server, which sends on the one address it found, gets `TRUSTED_PROXY_HOPS=1` and never `CLIENT_IP_HEADER`. Previews get the same as production, and `try` sets `x-real-ip` on its Railway VM. Either setting in the env file replaces both defaults, for another proxy in front. Unset, the app takes the connection's address, which is right only when nothing stands in front of it. Neither is ever reported as unset, and projects from Starters that predate them ignore them.
+
 ### Preview deployments
 
 In a project that deploys to Vercel or Railway, `pnpm clubedge deploy --preview` deploys the current Git branch next to production, after a first `deploy`:
@@ -341,27 +381,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.41.1
+create-clubedge-app v0.42.0
         |
         v
-Clubedge Starter v0.26.1
-commit 93429784e265c9dc8eb8f8c87169e7b42732719f
+Clubedge Starter v0.27.0
+commit 5f0e7e57131c4c56305d67edfd2e7366618d7b7c
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.41.1` | `clubedge-starter@v0.26.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.42.0` | `clubedge-starter@v0.27.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.26.1` tag is expected to resolve to commit
-`93429784e265c9dc8eb8f8c87169e7b42732719f`. The CLI verifies this before
+The `v0.27.0` tag is expected to resolve to commit
+`5f0e7e57131c4c56305d67edfd2e7366618d7b7c`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.26.1`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.27.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -369,7 +409,7 @@ Every generated project records its CLI version, Starter repository, Starter ref
 
 Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.
 
-The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. Schema 3 adds `modules`: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, the root `package.json` scripts it sets, and the options it requires. Files listed under `conditional` contain `clubedge:if <condition>` / `clubedge:end` blocks (in `#`, `//`, `<!-- -->`, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; `clubedge:if starter-repository` marks sections for Starter maintainers only. The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
+The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. Schema 3 adds `modules`: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, the root `package.json` scripts it sets, and the options it requires. Files listed under `conditional` contain `clubedge:if <condition>` / `clubedge:end` blocks (in `#`, `//`, `<!-- -->`, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; `clubedge:if starter-repository` marks sections for Starter maintainers only. Schema 4 moves each app's description into its own stack pack, placed in a slot (`--framework`, `--api`), and schema 5 adds the shell role for a mobile app (`--shell`); see [docs/stack-packs.md](docs/stack-packs.md). The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
 
 The CLI first builds a plan (the files to copy and the edits to make), which `--dry-run` prints, and then applies it. The source is organized the same way:
 
@@ -416,7 +456,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.26.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.27.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -468,6 +508,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.39.0 | v0.25.0 | Starter v0.25.0: every module on React + Vite with Hono, and account settings on React + Vite |
 | 0.40.0 | v0.26.0 | Starter v0.26.0: every module on React + Vite with FastAPI (pg-boss excepted) |
 | 0.41.0 | v0.26.0 | A conflicted package.json no longer breaks later commands (`--detailed-exit-code`); doctor finds conflict markers; projects own their version and README |
+| 0.42.0 | v0.27.0 | Starter v0.27.0: mobile apps with Capacitor (`--shell capacitor`, template schema 5); client addresses per platform; Docker Compose behind Caddy, with images on GHCR |
 
 ## Community
 

package/dist/core/deploy.js

@@ -11,40 +11,39 @@ export function serviceName(packageName) {
     return name || "web";
 }
 /**
- * A Docker Compose production topology rendered from the selected stack service descriptors.
- * `frontendKeys` are the variables the frontend's env example lists: its VITE_* values become build
- * arguments (Vite compiles them in), the others runtime variables, such as Better Auth's when the
- * frontend's server runs auth. Compose reads their values from its --env-file.
+ * Where the app finds a request's client address: CLIENT_IP_HEADER, a header the platform's edge
+ * sets to it (overwriting any copy the client sent), or TRUSTED_PROXY_HOPS, the number of proxies
+ * of your own that append to X-Forwarded-For (the app reads the entry that many places from the
+ * right). Unset, the app is exposed directly and takes the socket's address. Both have safe
+ * defaults, so deploy never reports them as unset.
  */
-export function dockerComposeSource(services, frontendKeys = []) {
-    const api = Object.values(services).find((service) => service.role === "api");
-    const web = Object.values(services).find((service) => service.role === "frontend");
-    const mapping = (indent, values) => values.map(([key, value]) => `\n${indent}${key}: ${value}`).join("");
-    const fromEnv = (key, fallback = "") => `\${${key}:-${fallback}}`;
-    const buildKeys = frontendKeys.filter((key) => key.startsWith("VITE_"));
-    // API_URL is the API's address on the Compose network, and PORT the one the image declares.
-    const runtimeKeys = frontendKeys.filter((key) => !key.startsWith("VITE_") && key !== "API_URL" && key !== "PORT");
-    // Better Auth runs in the frontend's server: the API asks it for the session over the Compose network.
-    const authUrl = web && frontendKeys.includes("BETTER_AUTH_URL") ? `http://${web.id}:${web.port}` : null;
-    const rows = Object.entries(services).map(([, service]) => {
-        const name = service.id;
-        const frontend = service.role === "frontend";
-        const buildArgs = frontend && buildKeys.length
-            ? `\n      args:${mapping("        ", buildKeys.map((key) => [key, fromEnv(key)]))}`
-            : "";
-        // Better Auth's public URL defaults to the port Compose publishes.
-        const runtime = runtimeKeys.map((key) => [key, fromEnv(key, key === "BETTER_AUTH_URL" ? `http://localhost:${service.port}` : "")]);
-        // The API listens on every interface, whatever HOST the env file has from development.
-        const apiValues = [["HOST", "0.0.0.0"], ...(authUrl ? [["BETTER_AUTH_URL", authUrl]] : [])];
-        const apiEnv = service.role === "api" ? `\n    environment:${mapping("      ", apiValues)}` : "";
-        const env = frontend && api
-            ? `\n    environment:${mapping("      ", [["API_URL", `http://${api.id}:${api.port}`], ...runtime])}`
-            : `\n    env_file:\n      - path: .env.production\n        required: false${apiEnv}`;
-        const ports = frontend ? `\n    ports:\n      - "${service.port}:${service.port}"` : `\n    expose:\n      - "${service.port}"`;
-        const depends = frontend && api ? `\n    depends_on:\n      - ${api.id}` : "";
-        return `  ${name}:\n    build:\n      context: .\n      dockerfile: ${service.dockerfile}${buildArgs}${env}${ports}${depends}`;
-    });
-    return `# Generated from Clubedge stack descriptors. Build and start every app service together.\nservices:\n${rows.join("\n")}\n`;
+export const clientAddressKeys = ["CLIENT_IP_HEADER", "TRUSTED_PROXY_HOPS"];
+/** What deploy sets on the public service of each platform. */
+export const clientAddresses = {
+    railway: { CLIENT_IP_HEADER: "x-real-ip" },
+    // Render documents Cloudflare in front of every service; Cloudflare sets this header to the
+    // client's address and refuses requests that send their own. Render's X-Forwarded-For keeps the
+    // entries a client sent.
+    render: { CLIENT_IP_HEADER: "cf-connecting-ip" },
+    fly: { CLIENT_IP_HEADER: "fly-client-ip" },
+    vercel: { CLIENT_IP_HEADER: "x-real-ip" },
+    netlify: { CLIENT_IP_HEADER: "x-nf-client-connection-ip" },
+    // Docker Compose: Caddy, the one proxy in front, sets X-Forwarded-For to the client's address.
+    docker: { TRUSTED_PROXY_HOPS: "1" },
+};
+/**
+ * An API reached only through its frontend's server, which replaces X-Forwarded-For with the one
+ * client address it found: the API reads that entry, never a header a client could send.
+ */
+export const behindFrontend = { TRUSTED_PROXY_HOPS: "1" };
+/**
+ * A public service's client-address settings: the env file's when it sets either one (they
+ * describe one path to the client, so a default for the other would contradict it), else the
+ * platform's.
+ */
+export function clientAddressVariables(platform, envFile) {
+    const own = clientAddressKeys.filter((key) => envFile[key]);
+    return own.length ? Object.fromEntries(own.map((key) => [key, envFile[key]])) : { ...platform };
 }
 /** The variable each database's URL goes in. */
 export const databaseVariables = { postgres: "DATABASE_URL", redis: "REDIS_URL" };
@@ -106,18 +105,19 @@ export function parseEnvFile(text) {
 /**
  * The service's production variables. The CLI provides what it can: the database URLs (references
  * to Railway's databases by default), a generated Better Auth secret (unless the service already
- * has one), the public URL, and the port. Values from --env-file come next and win over those;
- * their database URLs replace the platform's, except local ones (a development env file).
- * Everything else the example lists is reported as unset; values the service already has count as set.
+ * has one), the public URL, the port, and where the client's address is. Values from --env-file
+ * come next and win over those; their database URLs replace the platform's, except local ones (a
+ * development env file). Everything else the example lists is reported as unset; values the
+ * service already has count as set.
  */
 export function planVariables(input) {
-    const { modules, keys, url, envFile, secret, attached = [], port = appPort } = input;
+    const { modules, keys, url, envFile, secret, attached = [], port = appPort, clientAddress = {} } = input;
     const existing = { ...input.existing, ...Object.fromEntries(attached.map((key) => [key, "(attached)"])) };
     const external = externalDatabaseUrls(modules, envFile);
     const databases = input.databases ?? railwayReferences(databasesFor(modules, Object.keys(external)));
     const provided = { NODE_ENV: "production", PORT: String(port), ...databases };
     // The public URL under both names: TanStack Start reads APP_URL, Next.js NEXT_PUBLIC_APP_URL.
-    const set = { ...provided, APP_URL: url, NEXT_PUBLIC_APP_URL: url };
+    const set = { ...provided, APP_URL: url, NEXT_PUBLIC_APP_URL: url, ...clientAddressVariables(clientAddress, envFile) };
     if (modules.auth === "better-auth" && !existing.BETTER_AUTH_SECRET)
         set.BETTER_AUTH_SECRET = secret();
     const databaseKeys = [...Object.values(databaseVariables), "DATABASE_URL_DIRECT"];
@@ -137,25 +137,28 @@ export function planVariables(input) {
     // database the app now uses, or blank it (blank counts as unset).
     else if (existing.DATABASE_URL_DIRECT)
         set.DATABASE_URL_DIRECT = set.DATABASE_URL ?? "";
-    // Optional: without it, migrations and the jobs worker use DATABASE_URL.
-    const unset = keys.filter((key) => set[key] === undefined && !existing[key] && key !== "DATABASE_URL_DIRECT");
+    // Optional: without a direct URL, migrations and the jobs worker use DATABASE_URL, and the
+    // client-address settings have safe defaults.
+    const optional = ["DATABASE_URL_DIRECT", ...clientAddressKeys];
+    const unset = keys.filter((key) => set[key] === undefined && !existing[key] && !optional.includes(key));
     return { set, unset };
 }
 /**
  * The variables of a frontend and an API deployed as two services. The API gets what planVariables
  * provides with the env file's server values, and the frontend's URL. The frontend gets its port,
- * the env file's VITE_* build values, and the runtime values its own example lists. With Better
- * Auth the frontend's server runs auth: it gets the API's database, the secret (generated unless
- * the service already has one), and BETTER_AUTH_URL, the public URL the API asks for the session.
- * Each service's unset variables come from its own example.
+ * where the client's address is, the env file's VITE_* build values, and the runtime values its
+ * own example lists. With Better Auth the frontend's server runs auth: it gets the API's database,
+ * the secret (generated unless the service already has one), and BETTER_AUTH_URL, the public URL
+ * the API asks for the session. Each service's unset variables come from its own example.
  */
 export function planServicePair(input) {
     const { modules, frontendKeys, apiKeys, url, existing, envFile, secret, databases, ports } = input;
     const betterAuth = modules.auth === "better-auth";
     // A development env file's localhost URL would send sign-in links to this machine.
     const authUrl = envFile.BETTER_AUTH_URL && !isLocalUrl(envFile.BETTER_AUTH_URL) ? envFile.BETTER_AUTH_URL : url;
-    const apiEnv = Object.fromEntries(Object.entries(envFile).filter(([key]) => !key.startsWith("VITE_")));
-    const api = planVariables({ modules, keys: apiKeys, url, existing: existing.api, envFile: apiEnv, secret, databases, port: ports.api });
+    // The env file's client-address settings are the public frontend's: the API is behind it.
+    const apiEnv = Object.fromEntries(Object.entries(envFile).filter(([key]) => !key.startsWith("VITE_") && !clientAddressKeys.includes(key)));
+    const api = planVariables({ modules, keys: apiKeys, url, existing: existing.api, envFile: apiEnv, secret, databases, port: ports.api, clientAddress: behindFrontend });
     // Better Auth's secret belongs to the frontend's server; the API only asks it for the session.
     if (!apiEnv.BETTER_AUTH_SECRET)
         delete api.set.BETTER_AUTH_SECRET;
@@ -165,8 +168,8 @@ export function planServicePair(input) {
     // The image listens on every interface: its Dockerfile sets HOST.
     api.unset = api.unset.filter((key) => api.set[key] === undefined && key !== "HOST");
     // railway.ts sets API_URL to the API's private address; the platform provides the database.
-    const provided = ["API_URL", "PORT", "BETTER_AUTH_URL", ...Object.values(databaseVariables), "DATABASE_URL_DIRECT"];
-    const set = { PORT: String(ports.frontend) };
+    const provided = ["API_URL", "PORT", "BETTER_AUTH_URL", ...Object.values(databaseVariables), "DATABASE_URL_DIRECT", ...clientAddressKeys];
+    const set = { PORT: String(ports.frontend), ...clientAddressVariables(input.clientAddress, envFile) };
     for (const [key, value] of Object.entries(envFile)) {
         if (value && (key.startsWith("VITE_") || (frontendKeys.includes(key) && !provided.includes(key))))
             set[key] = value;
@@ -179,8 +182,10 @@ export function planServicePair(input) {
         if (!set.BETTER_AUTH_SECRET && !existing.frontend.BETTER_AUTH_SECRET)
             set.BETTER_AUTH_SECRET = secret();
     }
-    // Optional: without VITE_API_URL the browser calls the API through the frontend's /api proxy.
-    const unset = frontendKeys.filter((key) => set[key] === undefined && !existing.frontend[key] && !["API_URL", "VITE_API_URL"].includes(key));
+    // Optional: without VITE_API_URL the browser calls the API through the frontend's /api proxy,
+    // and the client-address settings have safe defaults.
+    const optional = ["API_URL", "VITE_API_URL", ...clientAddressKeys];
+    const unset = frontendKeys.filter((key) => set[key] === undefined && !existing.frontend[key] && !optional.includes(key));
     return { frontend: { set, unset }, api };
 }
 /**
@@ -633,3 +638,224 @@ export function parseRenderEnv(body) {
     }
     return values;
 }
+/* ------------------------------------ Docker ------------------------------------ */
+// A server of your own: Docker Compose runs each app's image behind Caddy, which serves the domain
+// over HTTPS, and a GitHub workflow publishes the images to GitHub's container registry.
+/** The app of a full-stack project, whose stack records no service: the root Dockerfile's image. */
+export const fullstackService = {
+    id: "web",
+    role: "fullstack",
+    app: "apps/web",
+    dockerfile: "Dockerfile",
+    port: appPort,
+    healthPath: "/api/health",
+    platforms: ["docker"],
+};
+/** The service the public reaches: a frontend, whose API stays private, else the full-stack app. */
+export function publicService(services) {
+    const apps = Object.values(services);
+    return apps.find(({ role }) => role === "frontend") ?? apps.find(({ role }) => role === "fullstack") ?? fullstackService;
+}
+/**
+ * The values an app's image compiles in, which its Dockerfile takes as build arguments, from the
+ * variables its env example lists: a Vite frontend's VITE_* values, and Next.js's public URL.
+ */
+export function buildArgumentKeys(service, keys) {
+    if (service.role === "frontend")
+        return keys.filter((key) => key.startsWith("VITE_"));
+    return service.role === "fullstack" ? keys.filter((key) => key === "NEXT_PUBLIC_APP_URL") : [];
+}
+/**
+ * compose.yaml for a server of your own. Each app runs its image, pulled from IMAGE_PREFIX (where
+ * release-images.yml publishes them) at TAG, or built there with --build. Only Caddy publishes
+ * ports: it serves DOMAIN over HTTPS, with certificates it obtains and renews. `frontendKeys` are
+ * the variables the public app's env example lists: the values its image compiles in become build
+ * arguments, and a frontend's others runtime variables, such as Better Auth's when the frontend's
+ * server runs auth. Compose reads their values from its --env-file; the public URL defaults to
+ * https://DOMAIN.
+ */
+export function dockerComposeSource(project, services, frontendKeys = []) {
+    const apps = Object.values(services);
+    const api = apps.find((service) => service.role === "api");
+    const web = publicService(services);
+    const fromEnv = (key, fallback = "") => `\${${key}:-${fallback}}`;
+    const publicUrl = "https://${DOMAIN}";
+    const behindCaddy = clientAddresses.docker;
+    const behindWeb = behindFrontend;
+    // API_URL is the API's address on the Compose network, PORT the one the image declares, and the
+    // client-address settings default to Caddy's.
+    const runtimeKeys = frontendKeys.filter((key) => !key.startsWith("VITE_") && !["API_URL", "PORT", ...clientAddressKeys].includes(key));
+    // Better Auth runs in the frontend's server: the API asks it for the session over the Compose network.
+    const authUrl = api && frontendKeys.includes("BETTER_AUTH_URL") ? `http://${web.id}:${web.port}` : null;
+    const environment = (service) => {
+        if (service.role === "api") {
+            return [
+                // The API listens on every interface, whatever HOST the env file has from development.
+                "      HOST: 0.0.0.0",
+                `      # Reached only through ${web.id}, which passes on the client's address as the one X-Forwarded-For entry.`,
+                ...clientAddressKeys.map((key) => `      ${key}: ${JSON.stringify(behindWeb[key] ?? "")}`),
+                ...(authUrl ? [`      BETTER_AUTH_URL: ${authUrl}`] : []),
+            ];
+        }
+        // A frontend has no env_file: CLIENT_IP_HEADER from the env file needs a line of its own.
+        const address = [
+            "      # Caddy, the one proxy in front, sets X-Forwarded-For to the client's address.",
+            ...(service.role === "frontend" ? clientAddressKeys : Object.keys(behindCaddy)).map((key) => `      ${key}: ${fromEnv(key, behindCaddy[key])}`),
+        ];
+        if (service.role !== "frontend")
+            return [...appUrlKeys.map((key) => `      ${key}: ${fromEnv(key, publicUrl)}`), ...address];
+        return [
+            ...(api ? [`      API_URL: http://${api.id}:${api.port}`] : []),
+            ...address,
+            ...runtimeKeys.map((key) => `      ${key}: ${fromEnv(key, key === "BETTER_AUTH_URL" ? publicUrl : "")}`),
+        ];
+    };
+    const rows = apps.flatMap((service) => {
+        const args = buildArgumentKeys(service, frontendKeys);
+        return [
+            `  ${service.id}:`,
+            `    image: \${IMAGE_PREFIX:-${project}}-${service.id}:\${TAG:-latest}`,
+            "    build:",
+            "      context: .",
+            `      dockerfile: ${service.dockerfile}`,
+            ...(args.length ? ["      args:", ...args.map((key) => `        ${key}: ${fromEnv(key, key === "NEXT_PUBLIC_APP_URL" ? publicUrl : "")}`)] : []),
+            // The frontend gets only the values it needs; the API's stay with the API.
+            ...(service.role === "frontend" ? [] : ["    env_file:", "      - path: .env.production", "        required: false"]),
+            "    environment:",
+            ...environment(service),
+            "    expose:",
+            `      - "${service.port}"`,
+            ...(service.role === "frontend" && api ? ["    depends_on:", `      - ${api.id}`] : []),
+            "    restart: unless-stopped",
+        ];
+    });
+    return [
+        "# Generated by create-clubedge-app deploy. Caddy serves the app at DOMAIN over HTTPS, with",
+        "# certificates it obtains and renews; the apps listen only on the Compose network. Each app's",
+        "# image is pulled from IMAGE_PREFIX at TAG (release-images.yml publishes them), or built here",
+        "# with --build. Run it with: docker compose --env-file .env.production up -d",
+        "services:",
+        ...rows,
+        "  caddy:",
+        "    image: caddy:2",
+        "    restart: unless-stopped",
+        "    ports:",
+        '      - "80:80"',
+        '      - "443:443"',
+        '      - "443:443/udp"',
+        "    environment:",
+        '      DOMAIN: "${DOMAIN:?Set DOMAIN in .env.production to the domain that points at this server}"',
+        "    volumes:",
+        "      - ./Caddyfile:/etc/caddy/Caddyfile:ro",
+        "      - caddy-data:/data",
+        "      - caddy-config:/config",
+        "    depends_on:",
+        `      - ${web.id}`,
+        "",
+        "volumes:",
+        "  caddy-data:",
+        "  caddy-config:",
+        "",
+    ].join("\n");
+}
+/** The Caddyfile compose.yaml mounts: Caddy serves DOMAIN over HTTPS and passes every request to the public app. */
+export function caddyfileSource(services) {
+    const web = publicService(services);
+    return [
+        "# Generated by create-clubedge-app deploy. Caddy serves DOMAIN, from .env.production, over HTTPS:",
+        "# it obtains the certificate and renews it by itself once the domain's DNS points at this server.",
+        "{$DOMAIN} {",
+        `\treverse_proxy ${web.id}:${web.port}`,
+        "}",
+        "",
+    ].join("\n");
+}
+export const releaseImagesPath = ".github/workflows/release-images.yml";
+/**
+ * The workflow that publishes the images compose.yaml pulls: each published GitHub release builds
+ * every app's image for linux/amd64 and linux/arm64 and pushes it to the repository's GitHub
+ * Container Registry, tagged with the version. Not on tag pushes: a deleted tag would leave its
+ * images behind. The values an image compiles in come from the repository's variables.
+ */
+export function releaseImagesWorkflowSource(services, frontendKeys = []) {
+    const argsByService = Object.values(services).map((service) => ({ service, args: buildArgumentKeys(service, frontendKeys) }));
+    const matrix = argsByService.flatMap(({ service, args }) => {
+        return [
+            `          - service: ${service.id}`,
+            `            dockerfile: ${service.dockerfile}`,
+            "            context: .",
+            ...(args.length
+                ? ["            # The image compiles these in: set them as repository variables.", "            build-args: |", ...args.map((key) => `              ${key}=\${{ vars.${key} }}`)]
+                : []),
+        ];
+    });
+    return [
+        "# Generated by create-clubedge-app deploy. Each published GitHub release builds every app's image",
+        "# for linux/amd64 and linux/arm64 and pushes it to this repository's container registry as",
+        "# ghcr.io/<owner>/<repository>-<service>, tagged with its version, <major>.<minor>, and latest;",
+        "# compose.yaml runs them with IMAGE_PREFIX=ghcr.io/<owner>/<repository>. Run by hand on the",
+        "# default branch, it pushes edge. New packages are private until you make them public.",
+        "name: Release images",
+        "",
+        "on:",
+        "  release:",
+        "    types: [published]",
+        "  workflow_dispatch:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "  packages: write",
+        "",
+        "jobs:",
+        "  image:",
+        "    name: image (${{ matrix.service }})",
+        "    runs-on: ubuntu-24.04",
+        "    strategy:",
+        "      matrix:",
+        "        include:",
+        ...matrix,
+        "    steps:",
+        "      - uses: actions/checkout@v7",
+        "      # Builds the arm64 image on GitHub's amd64 runners.",
+        "      - uses: docker/setup-qemu-action@v4",
+        "      - uses: docker/setup-buildx-action@v4",
+        "      - uses: docker/login-action@v4",
+        "        with:",
+        "          registry: ghcr.io",
+        "          username: ${{ github.actor }}",
+        "          password: ${{ secrets.GITHUB_TOKEN }}",
+        "      - id: meta",
+        "        uses: docker/metadata-action@v6",
+        "        with:",
+        "          # The action lowercases the name, as the registry requires.",
+        "          images: ghcr.io/${{ github.repository }}-${{ matrix.service }}",
+        "          flavor: latest=false",
+        "          tags: |",
+        "            type=semver,pattern={{version}}",
+        "            type=semver,pattern={{major}}.{{minor}}",
+        "            type=raw,value=latest,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}",
+        "            type=edge",
+        "            type=sha",
+        "      - uses: docker/build-push-action@v7",
+        "        with:",
+        "          context: ${{ matrix.context }}",
+        "          file: ${{ matrix.dockerfile }}",
+        "          platforms: linux/amd64,linux/arm64",
+        "          push: true",
+        "          tags: ${{ steps.meta.outputs.tags }}",
+        "          labels: ${{ steps.meta.outputs.labels }}",
+        // Only when an image compiles values in: the matrix has no build-args otherwise.
+        ...(argsByService.some(({ args }) => args.length) ? ["          build-args: ${{ matrix.build-args }}"] : []),
+        "          cache-from: type=gha,scope=${{ matrix.service }}",
+        "          cache-to: type=gha,mode=max,scope=${{ matrix.service }}",
+        "",
+    ].join("\n");
+}
+/**
+ * Where release-images.yml publishes a GitHub repository's images, as compose.yaml's IMAGE_PREFIX:
+ * ghcr.io/<owner>/<repository> in lowercase, as the registry requires. Null for other Git hosts.
+ */
+export function ghcrImagePrefix(remote) {
+    const path = /^https:\/\/github\.com\/(.+)$/.exec(renderRepoUrl(remote) ?? "")?.[1];
+    return path ? `ghcr.io/${path.toLowerCase()}` : null;
+}

package/dist/core/env.js

@@ -90,7 +90,16 @@ export function updateEnvFile(local, baseExample, targetExample) {
         // The last element is the end of the file after its final newline, not a blank line.
         const followedByBlank = position + 1 < lines.length - 1 && lines[position + 1].trim() === "";
         const reuseBlank = between[0]?.trim() === "" && followedByBlank;
-        lines.splice(position + (reuseBlank ? 2 : 1), 0, ...(reuseBlank ? between.slice(1) : between));
+        const inserted = reuseBlank ? between.slice(1) : between;
+        const insertAt = position + (reuseBlank ? 2 : 1);
+        lines.splice(insertAt, 0, ...inserted);
+        // A variable that ends its section in the target keeps a blank line before the next section,
+        // which a reused separator would otherwise leave above the variable instead. (The last
+        // element of each split is the end of the file, not a blank line.)
+        const endsSection = at + 1 < target.length - 1 && target[at + 1].trim() === "";
+        const next = insertAt + inserted.length;
+        if (endsSection && next < lines.length - 1 && lines[next].trim() !== "")
+            lines.splice(next, 0, "");
     });
     let text = lines.join(eol);
     // Removed variables can leave blank lines in a row, as removed template blocks do.