Deploy by project type
Static sites
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:
| Framework | Detected by | Folder served |
|---|---|---|
| Vite (React, Vue, Svelte, Solid, Preact…) | vite in package.json | dist/ |
| Create React App | react-scripts in package.json | build/ |
| Angular | @angular/core + angular.json | the output path in angular.json |
| Astro (static output) | astro in package.json | dist/ |
| Next.js static export | output: 'export' in next.config | out/ |
| React Router (SPA mode) | ssr: false in react-router config | build/client/ |
| Plain HTML | index.html at the root, or a public/ folder, or a Staticfile | root, 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.jsonat the root of the repository, with abuildscript.- A committed lock file (
package-lock.json,yarn.lock,pnpm-lock.yamlorbun.lockb). It decides the package manager and makes builds repeatable. - Pin the Node version with
"engines": { "node": "20.x" }in package.json, or an.nvmrcfile. Otherwise the current LTS is used. - No custom
startscript. Astartscript such asserve -s distorvite previewmakes 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.
{
"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#
New → Static site
In the dashboard, click New and choose Static site. The port (80) is set for you.
Pick the repository and branch
Connect GitHub if you haven't, then choose the repository and branch.
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.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.
VITE_API_URL=https://api-7h2k9q.cloud.crowtherlabs.comOption 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.
# 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/0Never 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:
root: site
index_fallback: trueClient-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.
# ---- 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 80node_modules
dist
.git
.env*
!.env.productionBefore you deploy#
npm run buildworks on a clean clone (rm -rf node_modules && npm ci && npm run build).- The lock file is committed.
- There is no custom
startscript. - 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.