Deploy by project type
Web services
Need a background worker or scheduler?
Use a Container App. The example runs an API and worker together with PostgreSQL and Redis.
The three rules#
Almost every failed web service deploy breaks one of these:
| Rule | Why |
|---|---|
| Listen on port 3000 | Traffic is sent to port 3000 inside your container. An app on 8000, 5000 or 8080 deploys "fine" and then answers every request with 502 Bad Gateway. |
Listen on 0.0.0.0, not localhost | localhost / 127.0.0.1 only accepts connections from inside the container itself, so the router can't reach you — also a 502. |
| Keep nothing on local disk | The filesystem is reset on every deploy. Use a database or object storage for anything you need to keep. |
Always set PORT=3000
The platform does not set a PORT variable for you, and several start commands fall back to their own default when it is missing — Python's to 8000. Add PORT=3000 to the service's environment variables, and read it in your code with 3000 as the fallback. Then both are right.
How your app is built#
Repositories without a Dockerfile are built by Railpack. It recognises the language from the files at the root of the repository, installs dependencies with the right package manager, runs your build, and decides the start command:
| Language | Recognised by | Start command used |
|---|---|---|
| Node.js | package.json | the start script → else main in package.json → else index.js / index.ts |
| Python | requirements.txt, pyproject.toml, Pipfile, or main.py / app.py | detected per framework — see below |
| Go | go.mod | the compiled binary |
| Others | Ruby, PHP, Java, Rust, Deno, Bun, Elixir, … | see railpack.com |
Setting the commands yourself: railpack.json
When detection guesses wrong — the app lives in src/, the entry file has an unusual name, or you need an extra build step — add a railpack.json at the root. The startCommand is the one you will use most:
{
"$schema": "https://schema.railpack.com",
"deploy": {
"startCommand": "node dist/server.js"
}
}Use railpack.json, not the dashboard fields
The Build command and Start command boxes under Advanced build overrides on the New screen are not applied to builds yet. Put commands in railpack.json (or package.json scripts), where they are versioned with your code anyway.
Node.js#
Express / Fastify / Koa
const express = require("express");
const app = express();
// TLS is terminated by the platform's router, which forwards the original
// scheme and client IP. Trust it, or secure cookies, redirects and
// rate-limiting by IP all see "http" and the router's address.
app.set("trust proxy", 1);
app.use(express.json());
app.get("/health", (req, res) => res.send("ok"));
app.get("/api/hello", (req, res) => res.json({ hello: "world" }));
const port = Number(process.env.PORT) || 3000;
app.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));{
"name": "orders-api",
"engines": { "node": "20.x" },
"scripts": {
"start": "node server.js"
},
"dependencies": {
"express": "^4.21.0"
}
}With TypeScript, compile in a build script and start the compiled output:
{
"scripts": {
"build": "tsc -p tsconfig.json",
"start": "node dist/server.js"
}
}NestJS
Point start at the compiled entry — not nest start, which needs the Nest CLI at runtime — and listen on all interfaces:
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.getHttpAdapter().getInstance().set("trust proxy", 1);
await app.listen(Number(process.env.PORT) || 3000, "0.0.0.0");
}
bootstrap();{
"scripts": {
"build": "nest build",
"start": "node dist/main.js"
}
}Next.js (with a server)
The default scripts already work — next start listens on 3000 unless PORT says otherwise:
{
"scripts": {
"build": "next build",
"start": "next start"
}
}NEXT_PUBLIC_ variables are baked in at build time
Dashboard variables reach your server at runtime, so process.env.DATABASE_URL in server code works.NEXT_PUBLIC_* values are also available, but they are copied into the browser bundle during next build: after changing one, press Settings → Redeploy to build again. See Environment variables → build time.
A Next.js app with output: 'export' has no server — deploy it as a Static site instead.
Python#
Railpack detects the framework and starts it on ${PORT:-8000} — which is why PORT=3000 must be set. For anything beyond a single main.py, write the start command in railpack.json so there is no guessing.
FastAPI
| Railpack's default | uvicorn main:app --host 0.0.0.0 --port $PORT |
| Needs | the app object named app in main.py at the root, and uvicorn installed |
fastapi==0.115.*
uvicorn[standard]==0.32.*from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health():
return {"ok": True}App in a package (for example app/main.py)? Say so explicitly. --proxy-headers makes request.url report https and the real client IP:
{
"$schema": "https://schema.railpack.com",
"deploy": {
"startCommand": "uvicorn app.main:app --host 0.0.0.0 --port 3000 --proxy-headers --forwarded-allow-ips='*'"
}
}Flask
Railpack runs gunicorn --bind 0.0.0.0:$PORT main:app, so add gunicorn to your requirements and name the module and object accordingly — or set the command:
{
"$schema": "https://schema.railpack.com",
"deploy": {
"startCommand": "gunicorn --bind 0.0.0.0:3000 --workers 2 app:app"
}
}Django
Railpack runs python manage.py migrate and then gunicorn with your project's WSGI module. Add gunicorn and whitenoise (to serve static files) to requirements, and make these settings production-safe:
import os
DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
# Your platform address and any custom domain.
ALLOWED_HOSTS = [".cloud.crowtherlabs.com", "api.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://*.cloud.crowtherlabs.com", "https://api.example.com"]
# HTTPS ends at the platform's router; trust the header it forwards.
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
STATIC_ROOT = BASE_DIR / "staticfiles"
MIDDLEWARE.insert(1, "whitenoise.middleware.WhiteNoiseMiddleware")Collect static files as part of the build, and pin the start command:
{
"$schema": "https://schema.railpack.com",
"steps": {
"build": {
"commands": ["...", "python manage.py collectstatic --noinput"]
}
},
"deploy": {
"startCommand": "python manage.py migrate && gunicorn config.wsgi:application --bind 0.0.0.0:3000"
}
}"..." keeps Railpack's own build commands and appends yours.
Python version and package managers
Pin the version with a .python-version file (e.g. 3.12); otherwise a recent 3.13 is used. pip (requirements.txt), Poetry, uv, PDM and Pipenv are all recognised from their lock files.
Go#
package main
import (
"net/http"
"os"
)
func main() {
port := os.Getenv("PORT")
if port == "" {
port = "3000"
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("ok")) })
http.ListenAndServe("0.0.0.0:"+port, nil)
}Keep go.mod at the repository root. Railpack builds the module and runs the resulting binary.
Deploy it#
- New → Web service, pick the repository and branch.
- Environment variables: at least
PORT=3000, plus yourDATABASE_URL, secrets and so on. - Press Deploy. The log ends with the HTTPS address.
Service settings#
Health-check path — leave it empty for now
Important
A health-check path currently opens the app's port on the server itself, so two services on the same server with the same port — or more than one replica — collide and the deploy fails. The check is also a single request made the moment the container starts, with a 5-second timeout, so an app that needs a few seconds to boot fails it. Until this is improved, leave the field empty. Your app is still watched: its public address is checked every two minutes and an incident opens if it stops answering.
Replicas — keep 1
More than one replica only helps an app that keeps no state in memory. In-memory sessions, WebSocket and Server-Sent-Event connections, in-process caches and scheduled jobs all break or double up across replicas. Leave it at 1 unless you have designed for it.
Behind the router
Your app always receives plain HTTP from the platform's router, with X-Forwarded-Proto: https and X-Forwarded-For set. Trust those headers (the examples above do) so your framework knows the request was HTTPS.
Before you deploy#
- The app listens on
0.0.0.0and portprocess.env.PORT || 3000(or the equivalent). PORT=3000is in the service's environment variables.- The lock file is committed and the runtime version is pinned.
- The start command runs compiled code, not a dev server (
nodemon,--reload,next dev). - Nothing the app needs to keep is written to local disk.
- No secrets committed to the repository — they go in environment variables.