cabloy 5.1.107 → 5.1.108

package/.cabloy-version

@@ -1 +1 @@
-5.1.107
+5.1.108

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 5.1.108
+
+### Features
+
+- Improve Docker domain deployment support.
+
+### Improvements
+
+- Clarify shared deployment guidance.
+
 ## 5.1.107
 
 ### Features

package/cabloy-docs/.vitepress/config.mjs

@@ -41,6 +41,12 @@ const fullstackGroups = [
       { text: 'Suites and Modules', link: '/fullstack/suites-and-modules' },
     ],
   },
+  {
+    text: 'Fullstack / Deployment',
+    items: [
+      { text: 'Docker + Cloudflare Deployment', link: '/fullstack/deploy-cloudflare-docker' },
+    ],
+  },
   {
     text: 'Fullstack / Tutorials',
     items: [

package/cabloy-docs/backend/multi-instance-and-instance-resolution.md

@@ -84,6 +84,24 @@ A practical fallback rule is:
 
 - subdomain-based instance resolution only becomes relevant if custom getter, query-field, and header-field resolution did not already determine the instance name
 
+## Subdomain mapping and the default instance
+
+`SERVER_SUBDOMAINOFFSET` controls how many labels at the right side of a hostname are treated as the base domain. Its default value is `2`, which fits a two-label base domain such as `cabloy.test` or `example.com`.
+
+With that default, Vona derives the instance name from the remaining labels:
+
+| Hostname              | Derived instance name |
+| --------------------- | --------------------- |
+| `cabloy.test`         | `''`                  |
+| `acme.cabloy.test`    | `acme`                |
+| `eu.acme.cabloy.test` | `acme.eu`             |
+
+The last example is intentionally `acme.eu`: Koa reverses the remaining hostname labels before Vona joins `ctx.subdomains` with `.`.
+
+The empty name `''` is the configured default instance. It is not an implicit fallback for every hostname: it can be disabled or removed. Each non-empty subdomain-derived name, including a deeper name such as `acme.eu`, must refer to an explicitly configured and enabled instance. Requests for an unknown, disabled, or deleted instance do not fall back to the default instance.
+
+If the public base domain uses a different label shape, set an explicit `SERVER_SUBDOMAINOFFSET` override that matches that domain before relying on subdomain instance resolution.
+
 ## Instance edge cases to remember
 
 A few current-runtime edge cases are worth remembering:

package/cabloy-docs/backend/runtime-and-flavors.md

@@ -52,7 +52,6 @@ cd vona && npm run build
 cd vona && npm run build:docker
 cd vona && npm run start
 cd vona && npm run start:one
-cd vona && npm run start:docker
 ```
 
 In the current repo, those scripts map naturally to:
@@ -83,9 +82,10 @@ cd vona && npm run play
 cd vona && npm run build
 cd vona && npm run build:docker
 cd vona && npm run start
-cd vona && npm run start:docker
 ```
 
+`build:docker` produces Docker-oriented output. Run that output through the Docker Compose workflow rather than a direct Vona `start:docker` command.
+
 These scripts show that the same `prod` mode can still branch into different output/runtime shapes through flavor.
 
 ## What the CLI injects automatically

package/cabloy-docs/backend/scripts.md

@@ -52,14 +52,15 @@ From the root repository:
 npm run start
 ```
 
-Vona also supports single-process and docker-oriented start modes inside its own package:
+Vona also supports its normal and single-process start modes inside its own package:
 
 ```bash
 cd vona && npm run start
 cd vona && npm run start:one
-cd vona && npm run start:docker
 ```
 
+For Docker output, use the Docker Compose workflow after `npm run build:docker`; Docker does not use a direct Vona start command.
+
 ## Test and typecheck
 
 From the root repository:

package/cabloy-docs/frontend/ssr-env.md

@@ -17,9 +17,29 @@ Representative variables include:
 - `SSR_BODYREADYOBSERVER`
 - `SSR_API_BASE_URL`
 - `SSR_PROD_PORT`
+- `SSR_TRANSFERCACHE`
+- `SSR_TRANSFERCACHE_EXPIRES`
 
 These affect areas such as cookie-driven SSR behavior, theme defaults, body-load observation, server-side API targeting, and SSR production port behavior.
 
+## SSR response cache control
+
+`SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES` control the `Cache-Control` response header that Zova adds after an SSR page is rendered.
+
+- `SSR_TRANSFERCACHE=false` disables this header path.
+- Any other value enables it in the current configuration normalization.
+- `SSR_TRANSFERCACHE_EXPIRES=0` emits `Cache-Control: no-cache, no-store, must-revalidate`.
+- A positive number of seconds or an `ms`-style duration such as `10m` emits `Cache-Control: public, max-age=<seconds>`.
+
+Cabloy Basic uses different flavor defaults:
+
+| Flavor | Settings                                                  | SSR response header                   |
+| ------ | --------------------------------------------------------- | ------------------------------------- |
+| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `public, max-age=600`                 |
+| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `no-cache, no-store, must-revalidate` |
+
+A route can override the flavor default through its SSR route metadata. For Cloudflare cache-rule alignment that preserves these origin headers, see [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker).
+
 ## Theme implications of `SSR_COOKIE`
 
 `SSR_COOKIE` is not only a storage choice. It also changes what SSR can guarantee about theme-sensitive output.

package/cabloy-docs/fullstack/deploy-cloudflare-docker.md

@@ -0,0 +1,136 @@
+# Docker + Cloudflare Deployment
+
+<Badge type="tip" text="Common" />
+
+This guide deploys Cabloy Basic or Cabloy Start in two stages: first run the fullstack application on a cloud server with Docker Compose, then put Cloudflare orange-cloud proxying in front of that origin. It covers the Vona-integrated Zova Web and Admin SSR runtime shared by both editions.
+
+Run all commands from the repository for the edition you are using. This guide documents the shared deployment contract; verify edition-specific flavor names, SSR site baselines, project assets, and repository details in the active edition source.
+
+Cloudflare Pages and Cloudflare Workers are not supported deployment targets in this guide.
+
+## Deployment model
+
+```text
+Browser
+  -> Cloudflare orange cloud
+  -> origin Nginx in Docker Compose
+  -> Vona app with Web/Admin SSR
+  -> PostgreSQL and Redis
+```
+
+The Docker Compose origin is the application deployment. Cloudflare provides DNS, edge TLS, proxying, and response caching in front of that origin.
+
+## Stage 1: deploy the Docker origin
+
+On the cloud server, clone and initialize the repository for your edition, then build and start its Docker flavor:
+
+```bash
+npm run init
+npm run build:docker
+cd vona/docker-compose
+sudo COMPOSE_BAKE=true docker-compose build
+sudo docker-compose up -d
+```
+
+The Compose stack contains the application, Nginx, PostgreSQL, and Redis. Treat database passwords, persistent volumes, backups, firewall rules, operating-system updates, and server hardening as production operator responsibilities.
+
+In the repository for the edition you are using, `vona/docker-compose/` is the generated and ignored deployment directory, while `vona/docker-compose-original/` is the tracked source template. Initialization copies the template only when the generated directory does not already exist, so upgrading the repository does not automatically update an existing generated Nginx configuration. Reconcile or regenerate that local deployment configuration deliberately, and verify the current template in your edition repository.
+
+## Local preflight with `cabloy.test`
+
+Before using a public domain, test the same hostname model locally. Use the reserved test domain `cabloy.test`, not a public domain such as `test.com`.
+
+Map every hostname that you want to test in the local hosts file, or use local DNS. For example:
+
+```text
+127.0.0.1 cabloy.test acme.cabloy.test eu.acme.cabloy.test
+```
+
+`SERVER_SUBDOMAINOFFSET` defaults to `2`. It treats the rightmost two labels as the base domain:
+
+| Hostname              | Derived instance            |
+| --------------------- | --------------------------- |
+| `cabloy.test`         | `''` (the default instance) |
+| `acme.cabloy.test`    | `acme`                      |
+| `eu.acme.cabloy.test` | `acme.eu`                   |
+
+The default instance is an explicitly configured empty-name instance. It can be disabled or removed. Each non-empty derived instance name must also be explicitly configured and enabled before its hostname can serve application traffic. A missing, disabled, or deleted named instance does not fall back to the default instance.
+
+The Docker Nginx template preserves both the incoming `Host` and `X-Forwarded-Host`. This is necessary because Vona uses the forwarded host for host-sensitive URLs and subdomain instance resolution. Test through Nginx, not only by calling the app container directly.
+
+For the instance configuration shape and full resolution order, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution).
+
+## Origin HTTPS prerequisite
+
+Cloudflare TLS has two separate connections:
+
+```text
+Visitor <-> Cloudflare edge
+Cloudflare <-> origin Nginx
+```
+
+The shared Docker origin baseline listens on port 80 only. Verify the current Nginx template in your edition repository. Before enabling Cloudflare **Full (strict)**, provide a separately managed TLS-capable origin layer and a valid certificate that matches the origin hostname. For example, this can be an Nginx or ingress configuration managed by the deployment environment.
+
+Use Cloudflare **Full (strict)** for the production connection to the origin. Do not use Flexible mode: it leaves the Cloudflare-to-origin connection unencrypted and can produce incorrect scheme and security behavior. Enabling the orange cloud alone does not add HTTPS to the origin.
+
+For current Cloudflare requirements, see [Full (strict)](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/full-strict/).
+
+## Stage 2: put Cloudflare in front of the origin
+
+After the origin is reachable with its TLS configuration:
+
+1. Create the DNS record for the base hostname, such as `example.com`, pointing to the origin server.
+2. Enable the record's orange-cloud proxy status.
+3. If subdomain instance routing is required, add the required instance records or a suitable wildcard record, such as `*.example.com`.
+4. Keep the origin proxy configuration forwarding the original `Host` and `X-Forwarded-Host` values to Vona.
+5. Set the deployment environment to the public URL when it must produce canonical absolute URLs:
+
+   ```dotenv
+   SERVER_SERVE_PROTOCOL=https
+   SERVER_SERVE_HOST=example.com
+   SERVER_SUBDOMAINOFFSET=2
+   ```
+
+The base hostname resolves to the empty-name/default instance. For example, `acme.example.com` resolves to `acme`; a deeper hostname such as `eu.acme.example.com` resolves to `acme.eu` and requires that explicitly configured instance.
+
+For current Cloudflare proxy-record behavior, see [Proxied DNS records](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/).
+
+## Cloudflare Cache Rule
+
+Configure one Cache Rule for the SSR origin:
+
+1. **If incoming requests match:** All incoming requests.
+2. **Cache eligibility:** Eligible for cache.
+3. **Edge TTL:** Use the origin `Cache-Control` header when present; bypass cache when it is absent.
+
+Do not add another Cache Rule or response-header override that replaces the origin `Cache-Control` value for these routes.
+
+This rule is intentionally small. It makes a response eligible for caching but still lets the SSR response header decide whether Cloudflare stores it. A `no-store` response remains non-cacheable, and normal Cloudflare cacheability safeguards still apply.
+
+For current Cache Rule settings, see [Cache Rules settings](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/).
+
+## SSR cache contract
+
+Zova SSR writes the cache contract during rendering through `SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES`. The current public Cabloy Basic baseline uses these defaults:
+
+| Flavor | Default settings                                          | SSR response header                                  | Cloudflare result with this rule                                |
+| ------ | --------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `Cache-Control: public, max-age=600`                 | Eligible to cache for ten minutes, subject to Cloudflare policy |
+| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `Cache-Control: no-cache, no-store, must-revalidate` | Not stored                                                      |
+
+For Cabloy Start, verify the effective Web and Admin values in the licensed Start repository before creating the Cloudflare rule. The rule design remains the same: preserve and follow the origin `Cache-Control` response instead of replacing it.
+
+A route can override the flavor default through SSR route metadata. The Cloudflare rule follows the response contract; it does not replace it.
+
+For the public Basic environment-variable details, see [SSR Environment Variables](/frontend/ssr-env).
+
+## Deployment checks
+
+After the origin is running, verify the following before relying on Cloudflare traffic:
+
+1. The base hostname returns the expected default instance.
+2. Each configured subdomain resolves to its expected enabled instance.
+3. Nginx forwards the browser hostname instead of the literal value `localhost`.
+4. Web SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `public, max-age=600`.
+5. Admin SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `no-cache, no-store, must-revalidate`.
+6. After Cloudflare proxying is enabled, responses intended to be public-cacheable can be cached at the edge while responses marked `no-store` are not stored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.107",
+  "version": "5.1.108",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/docker-compose-original/config/nginx/conf.d/nginx.conf

@@ -12,7 +12,7 @@ server {
     proxy_http_version 1.1;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Host $server_name;
+    proxy_set_header X-Forwarded-Host $http_host;
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_set_header Host $http_host;
     proxy_set_header X-NginX-Proxy true;

package/vona/env/.env

@@ -9,7 +9,7 @@ APP_VERSION = 5.0.0
 SERVER_KEYS = vona__1596889047267_3245
 SERVER_GLOBALPREFIX = /api
 SERVER_PUBLICDIR =
-SERVER_SUBDOMAINOFFSET = 1
+SERVER_SUBDOMAINOFFSET = 2
 SERVER_WORKERS =
 SERVER_LISTEN_HOSTNAME = 0.0.0.0
 SERVER_LISTEN_PORT = 7102

package/vona/src/backend/config/config/config.ts

@@ -49,7 +49,7 @@ export default async function (app: VonaApplication) {
 
   // server
   const publicDir = env.SERVER_PUBLICDIR || getPublicPathPhysicalRoot(app);
-  const subdomainOffset = Number.parseInt(env.SERVER_SUBDOMAINOFFSET || '1');
+  const subdomainOffset = Number.parseInt(env.SERVER_SUBDOMAINOFFSET || '2');
   const workers = Number.parseInt(env.SERVER_WORKERS!);
   config.server = {
     keys: (env.SERVER_KEYS || '').split(','),