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.

Last updated 18 November 2026View as Markdown

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.
Did this page help you?