Deployment

A Dashfy app is a long-running server that serves the built client and streams data to it over WebSockets. Deploy it to any host that can run a persistent Node process.

Requirements

Dashfy needs a runtime environment that supports:

• a persistent Node process — the server stays running to hold WebSocket connections (static and serverless-only hosts are not enough)
• WebSockets — real-time updates stream over a Socket.IO connection
• environment variables — for API tokens your extensions need (for example GITHUB_TOKEN)

In production the server serves the built client and handles the WebSocket connection on a single PORT, so no separate frontend deployment is required.

Production build

Projects scaffolded from any template are already set up for this — pnpm build followed by pnpm start serves the dashboard and the WebSocket on one port. If you added Dashfy to an existing app, two things need to line up.

The client must build into a directory the server serves as static files, which defaults to build/:

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'build',
    emptyOutDir: true,
  },
})

Frameworks that emit the client into a nested directory don't need a post-build move — point the server at that directory with staticDir instead, which is resolved against baseDir (requires @getdashfy/server 0.2.0 or later):

staticDir: build/client

The templates split along those two lines: Astro sets outDir: './build', while React Router and TanStack Start keep their native output — build/client and dist/client — and set staticDir to match.

And the client must connect to the same origin in production, rather than the localhost:5001 default it uses in development:

export const App = () => {
  const serverUrl = import.meta.env.PROD ? window.location.origin : undefined

  return <Dashfy serverUrl={serverUrl} />
}

One-click hosts

Railway and Render both run a persistent Node process with WebSockets. The official demo is preconfigured for either host — pnpm build then pnpm start, with a health check at /health.

Railway

Railway is the recommended host — it deploys the dashfy-demo project in one click via railway.toml.

See the demo repository for the full build and start configuration.

Render

Render also deploys dashfy-demo in one click via render.yaml. Enter a GITHUB_TOKEN when prompted if you use the GitHub extension.

You can also create a Web Service in the Render dashboard, connect the repo, and use the same build and start commands. A Blueprint is only needed if you want Render to apply render.yaml automatically.

Editing configuration

Docker

Every template includes a Dockerfile that builds the client and runs the server in a single container. From your project directory:

docker build -t my-dashfy-app .
docker run --rm -p 5001:5001 my-dashfy-app

The dashboard is then available at http://localhost:5001.

Environment variables

Extension tokens are only read by the server at runtime, so nothing secret is baked into the image. Pass them when you run the container:

docker run --rm -p 5001:5001 -e GITHUB_TOKEN=ghp_xxx my-dashfy-app

The server also honors PORT and binds 0.0.0.0, which is what lets a platform assign its own port:

docker run --rm -p 8080:8080 -e PORT=8080 my-dashfy-app

Changing dashboards without rebuilding

Mount your config over the copy inside the image. The server watches the file, so edits apply without restarting the container:

docker run --rm -p 5001:5001 \
  -v "$(pwd)/dashfy.config.yml:/app/dashfy.config.yml:ro" \
  my-dashfy-app

Reproducible builds

Templates ship without a lockfile, so the included Dockerfile runs a plain pnpm install. Commit pnpm-lock.yaml after your first install, then change the install steps to pnpm install --frozen-lockfile so every rebuild resolves the same versions.

Other hosts

Dashfy runs anywhere you can keep a Node process alive with WebSocket support — for example Fly.io or your own VPS. The Docker image works on any host that can run containers.

Live reference

The official demo runs the single-port production build described above at demo.dashfy.dev.