Docker + Cloudflare Deployment

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

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:

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:

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.

Origin HTTPS prerequisite

Cloudflare TLS has two separate connections:

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).

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:

   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.

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.

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.

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.