Docker & cross-host setups

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.