crutchcorn.dev / coldspa
[READ-ONLY] Mirror of https://github.com/crutchcorn/coldspa. Give your CFML a spa day. The Islands Architecture for ColdFusion. coldspa.dev
cfml coldfusion hydration islands islands-architecture react ssr vite vite-plugin vue
Star
Fork 0
Watch
coldspa docs docker.md
2.6 kB
Markdown
at main

title: Docker & cross-host setups description: How to configure Coldspa when CF and the Vite/Node sidecar run on different hosts (e.g. CF in Docker, Vite/Node on the host). #

When CF and the Vite/Node sidecar live on different hosts (most commonly: CF in a Docker container, Vite/Node on the host), two URLs need to work from different perspectives:

  • ssrUrl — CF → Node sidecar (server-to-server). Set this on the CF container.
  • viteUrl — Browser → Vite dev server. Set this so generated <script src="..."> URLs are reachable from the user's browser.

Don't run Node inside the CF container #

Coldspa's Application.cfc will try to spawn npm run dev and npm run ssr on application start. In a typical Docker setup the CF container has no Node installed, so the spawn fails — Coldspa detects that npm isn't on PATH and skips the spawn (with a one-line note in WEB-INF/coldspa-logs/manager.log). You're then expected to run Vite/Node externally and point ssrUrl/viteUrl at them.

If you'd like to suppress the auto-spawn entirely (and the npm probe), set COLDSPA_NO_BOOTSTRAP=1 on the CF container.

Common patterns #

Setup ssrUrl viteUrl
All on one host http://127.0.0.1:5174 (unset — defaults to localhost)
CF in Docker, Node on host (Win/Mac) http://host.docker.internal:5174 http://host.docker.internal:5173
CF in Docker, Node on host (Linux) http://host.docker.internal:5174 ¹ http://host.docker.internal:5173 ¹
Both in docker-compose (sidecar service coldspa-ssr) http://coldspa-ssr:5174 http://localhost:5173 ²

¹ On Linux, add --add-host=host.docker.internal:host-gateway to the CF container. ² The browser still hits localhost because Vite's port is published from the compose stack to the host.

Vite dev server host binding #

When viteUrl (or COLDSPA_VITE_URL) points at a non-localhost host, the Coldspa Vite plugin automatically:

  • binds the dev server to all interfaces (server.host: true)
  • adds the discovered hostname to server.allowedHosts so Vite 5.4+ doesn't reject the request with 403 Forbidden
  • sets server.origin and server.hmr.host so generated asset / HMR URLs use the external hostname

No extra Vite config is required — just set the URL.