# 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](configure-release-and-health-checks.md) and
[Scale an app](scale-an-app.md).

## 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](quotas.md).

## Related

- [Compose files](compose-files.md)
- [Deployments](deployments.md)
- `deploy.apps.create` · `dcloud deploy apps create` · `dcloud_app`
