Deploy by project type

Static sites

For frontends that build to plain files — React, Vue, Angular, Svelte, Astro, or hand-written HTML. The platform runs your build, then serves the output from a fast web server with HTTPS and client-side routing already handled. No Dockerfile and no server code needed.

Is this the right guide?#

Use a Static site when all of these are true:

  • Running your build produces a folder of HTML, CSS and JS (dist/, build/, out/…).
  • The app talks to its backend over HTTP from the browser.
  • It needs server-side rendering or API routes (Next.js with next start, Nuxt, Remix server, SvelteKit server) — that is a Web service.
  • It is a frontend and a backend in one repository — use a Container App so both deploy together.

Supported frameworks#

Builds are done by Railpack, which recognises these and serves their output with Caddy on port 80:

FrameworkDetected byFolder served
Vite (React, Vue, Svelte, Solid, Preact…)vite in package.jsondist/
Create React Appreact-scripts in package.jsonbuild/
Angular@angular/core + angular.jsonthe output path in angular.json
Astro (static output)astro in package.jsondist/
Next.js static exportoutput: 'export' in next.configout/
React Router (SPA mode)ssr: false in react-router configbuild/client/
Plain HTMLindex.html at the root, or a public/ folder, or a Staticfileroot, public/, or what Staticfile says

Not on the list? (Vue CLI, Gatsby, custom setups)

Use the Dockerfile below. It works for any tool that builds to a folder.

What your repository needs#

  • package.json at the root of the repository, with a build script.
  • A committed lock file (package-lock.json, yarn.lock, pnpm-lock.yaml or bun.lockb). It decides the package manager and makes builds repeatable.
  • Pin the Node version with "engines": { "node": "20.x" } in package.json, or an .nvmrc file. Otherwise the current LTS is used.
  • No custom start script. A start script such as serve -s dist or vite preview makes the build run that command instead of serving your files — usually on the wrong port. The frameworks' own defaults (react-scripts start, ng serve) are fine and are ignored.
package.json (Vite)
{
  "name": "customer-portal",
  "private": true,
  "engines": { "node": "20.x" },
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "vite": "^6.0.0",
    "@vitejs/plugin-react": "^4.3.0"
  }
}

Deploy it#

  1. New → Static site

    In the dashboard, click New and choose Static site. The port (80) is set for you.

  2. Pick the repository and branch

    Connect GitHub if you haven't, then choose the repository and branch.

  3. Add the values your build needs

    Add values your frontend reads while building, such as VITE_API_URL, as environment variables. A static site has no server, so they are used only by the build — read the next section.

  4. Deploy

    The log shows the framework Railpack detected, the build, and finally the address your site is live at.

Don't deploy a single-page app as a Web service

A Web service expects your app to listen on port 3000. The built-in static server listens on 80, so the deploy succeeds but every visit returns 502 Bad Gateway. Always choose Static site for Vite, CRA, Angular and plain HTML.

API URLs and other build-time values#

Variables such as VITE_API_URL, REACT_APP_API_URL or NEXT_PUBLIC_API_URL are copied into your JavaScript when it is built. There are three ways to provide them:

Option A — set them in the dashboard (simplest)

Environment variables set on the service are available while your site builds, so import.meta.env.VITE_API_URL (or process.env.REACT_APP_API_URL) picks them up. They end up inside your JavaScript, so changing one needs a new build: after saving, press Settings → Redeploy. A plain restart (Deployments → Redeploy) keeps the old values.

Environment variables
VITE_API_URL=https://api-7h2k9q.cloud.crowtherlabs.com

Option B — commit a .env.production file

Vite, Create React App and Next.js all read .env.production automatically during a production build. It is fine to commit, because everything in it ends up in the public JavaScript anyway. A value set in the dashboard wins over the same name in this file.

.env.production
# Public values only — anything here is visible to every visitor.
VITE_API_URL=https://api-7h2k9q.cloud.crowtherlabs.com
VITE_SENTRY_DSN=https://abc123@o0.ingest.sentry.io/0

Never put a secret in a frontend

API keys with write access, database passwords, private tokens: anything in a frontend build is downloadable by every visitor, whichever way it gets there. Secrets belong in your backend.

Option C — call the API on the same address

If the frontend and API are deployed together as a Container App, the frontend can call /api/… with no host at all, and there is nothing to configure. This is the most robust setup — the frontend never needs to know the API's address.

With your own Dockerfile or a Container App

When the site is built from your own Dockerfile, declare each value as an ARG (ARG VITE_API_URL) and it receives the dashboard variable of the same name — Dockerfile apps → build arguments. A Container App hands dashboard variables to the build through Compose build.args — Container Apps → build arguments.

Plain HTML sites#

No build step, no package.json: put index.html at the root of the repository (or your files in a public/ folder) and deploy as a Static site.

To serve a different folder, or to send unknown paths to index.html for a hand-rolled single-page app, add a Staticfile at the root:

Staticfile
root: site
index_fallback: true

Client-side routing#

For the supported frameworks, a request for a path that isn't a real file (for example /dashboard/settings) is answered with your index.html, so React Router, Vue Router and Angular routing work on refresh and on direct links. Nothing to configure.

Health checks#

Leave Settings → Health-check path empty

A health-check path on a Static site makes the deploy fail: the check needs the site's port ( 80) opened on the server itself, and that port is already used by the platform's router. Your site is still watched — the platform checks its public address every two minutes and raises an incident if it stops answering.

Full control: a Dockerfile for any static site#

For frameworks Railpack doesn't recognise, a non-standard output folder, or custom headers and redirects, add this Dockerfile at the root. The repository is then built from it instead (Dockerfile apps). Deploy it as a Static site — nginx listens on port 80.

Dockerfile
# ---- build ----
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build          # outputs to /app/dist — change below if yours differs

# ---- serve ----
FROM nginx:1.27-alpine
COPY --from=build /app/dist /usr/share/nginx/html
# Send unknown paths to index.html so client-side routing works on refresh.
RUN printf 'server {\n  listen 80;\n  root /usr/share/nginx/html;\n  location / { try_files $uri $uri/ /index.html; }\n  location = /health { return 200; }\n}\n' \
    > /etc/nginx/conf.d/default.conf
EXPOSE 80
.dockerignore
node_modules
dist
.git
.env*
!.env.production

Before you deploy#

  • npm run build works on a clean clone (rm -rf node_modules && npm ci && npm run build).
  • The lock file is committed.
  • There is no custom start script.
  • Public values the build needs are set as environment variables (or in .env.production) — and none of them is a secret.
  • You chose Static site, not Web service.