Apps and sources
What an app is made of, the four sources it can run from, and every setting it has with its rule and default.
An app is one deployable thing: a name, a source, a machine size and replica count, an environment, and the domains it answers on. Changing a setting takes effect on the next deployment.
Sources
The builder of an app says where its software comes from. Through the API, an app created
without a builder gets railpack.
| Builder | What you provide | What runs |
|---|---|---|
image |
an image reference; from your registry, with the repository selected, or any public image | that image |
compose |
a compose file, inline or at a path in a connected repository | every service in the file |
dockerfile |
a connected repository with a Dockerfile | an image the platform builds and pushes to your registry, then runs |
railpack |
a connected repository without a Dockerfile | an image the platform builds from the source, then runs |
In Create app, under Where does this app come from?, these are A container image, A
compose file and A repository; a repository app then chooses, under How is the image
built?, Dockerfile (built with BuildKit from the Dockerfile in the root directory) or
Railpack (detects the language, no Dockerfile needed). dockerfile and railpack need a
repository (400, The "railpack" builder builds from a repository, so a repository is required); image needs an image reference (400, An app that deploys a container image needs an image reference).
A short image reference is completed the way Docker reads it: nginx:1.27 is pulled as
docker.io/library/nginx:1.27.
App settings
| Field | Rule | Default |
|---|---|---|
name |
1–64 characters | required |
slug |
the first label of the default URL; lowercase letters, digits and hyphens, at most 63 characters, unique in the organization (409, An app with slug "…" already exists). Subdomain label in the console; cannot be changed later |
from the name |
port |
the port the published container listens on, 1–65535 (Container port) | API: 3000. Console: 8080, or 80 for an official nginx or httpd image |
instanceType |
one of the machine sizes offered (Machine size) | the region's default size |
replicas |
machines running the same container, 1–10 | 1 |
locations |
not taken by the create request; set it with an update (or on the Runtime tab). Where the machines run, spread in the order given, at most 3: fsn1 (Falkenstein) and/or nbg1 (Nuremberg); or hel1 (Helsinki, Finland), only when the organization allows EU locations outside Germany (Settings → Data location); never mixed across regions; anything else is refused with 400 |
the region's own location (fsn1) |
composeService, composePort |
compose apps only: the published service and its container port; the service must exist in the file, and if it declares ports the port must be one of them | required for compose |
releaseCommand |
up to 4096 characters; runs once per deployment with /bin/sh -c, from the new image and with the app's environment, before traffic moves; a non-zero exit fails the deployment |
none |
releaseService |
compose apps: the service whose image and environment run the release command | the published service |
releaseTimeoutSec |
10–3600; the release command is stopped and the deployment fails after this long | 600 |
healthCheck |
{ "path": "/api/health", "port": 3000, "expectedStatus": 200, "timeoutSec": 60 }; every field but path is optional; timeoutSec 5–1800 |
GET /, any status below 500, 60 seconds (180 for a compose app) |
composeHealthChecks |
compose apps: { "<service>": { "path": …, "port": … } } for up to 50 services other than the published one; without port the check fails on the machine |
none; a check without timeoutSec waits 120 seconds |
deployOnPush |
apps with a repository: deploy every push to the branch | on for a new app with a repository |
See Configure the release command and health checks and Scale an app.
Limits
- One published service per app.
- An app holds up to 1000 environment variables.
- A compose file is at most 128 KiB.
- How many apps an organization may have is a quota; see Quotas.