Create an app

Create an app to run a web service from a git repository or from a container image. You create it on the dashboard's New app page, or through the API. Creating it also starts its first deployment unless you turn that off, so a working app is live once its replicas pass their health check.

• Sign in to the dashboard. Apps is in the sidebar only while Apps is on for the platform (Limits and availability).
• For a git app, the repository must be on a public host and reachable over HTTPS. For a private repository, create an access token on your git host that can read it.
• For an image app, the image must be one that anyone can pull, such as a public image on GitHub Container Registry or Docker Hub.
• Make sure the app listens on the port in its PORT variable and answers its health check path (What your app must do).
• For an organization's app, you need the owner or admin role in the organization.
• You can have a set number of apps. The Apps list shows how many you have, such as 3 of 20 apps, and Regions, sizes and limits shows how to read it through the API.

1. Go to Apps in the sidebar and select New app….

2. Under App, type a Name, such as Web shop. The hint under it shows the address the app will answer at, such as It answers at web-shop.apps.example.net, with a short suffix when that name is taken.

3. Under Source, choose Git repository or Ready image.

   • For a git repository, fill in Repository, and change Branch when the app is not on main. Fill in Directory when the app is not at the top of the repository, and Access token when the repository is private.
   • For a ready image, fill in Image, such as ghcr.io/example/web:1.4.0.

4. Under Regions, choose Every region, or choose The regions I choose and tick each region you want. Then choose Replicas per region.

5. Under Run, check Port, Health check path and Size.

6. To change how a git app builds and starts, or to choose its name on the platform yourself, select Show settings on the last card. It is Build and start for a git app and Name on the platform for an image app.

7. Leave Start the first deployment now ticked to deploy as soon as the app exists, or untick it.

   Tip

   The form has no environment variables. When the app needs some to build or start, untick Start the first deployment now, add them on the app's Environment tab, then deploy (Set environment variables).

8. Select Create app.

When a field is wrong, the message under it says why, and the form keeps what you typed. Any other refusal appears above the buttons under Could not create the app.

The App card:

Name

What you call the app, up to 100 characters. You can change it later.

The Source card. Whether the app uses a Git repository or a Ready image cannot change later:

Repository

For a git app, the repository's HTTPS address, such as https://github.com/example/web-shop, with no user name, token, query or fragment in it.

Branch

The branch to build, main at first. Pushes to it deploy the app once you set up the push webhook.

Directory

Where the app lives inside the repository. Leave it empty when the app is at the top.

Access token

For a private repository. We keep it encrypted, use it only to fetch the code, and never show it again. The app shows its last four characters so you can tell which token it holds.

Image

For an image app. A reference such as ghcr.io/example/web:1.4.0, or one pinned to a digest such as ghcr.io/example/web@sha256:…. It cannot be in the platform's own registry, which only holds images built from git.

The Regions card:

Every region or The regions I choose

Every region that can run apps at the time of each deployment, which is the default, or up to 20 regions you tick. Each region shows its code and country.

Replicas per region

How many replicas run in each region, from 1 to 5, 1 at first.

The Run card:

Port

A number from 1 to 65535, 3000 at first, saved with the app. Each replica gets the port to listen on in its PORT variable, whatever this setting says.

Health check path

The path we request to decide that a replica is healthy, / at first. It starts with /, such as /healthz.

Size

The memory, CPU and disk each replica gets. Each option shows all three (Replicas and regions).

The Build and start card of a git app, under Show settings:

Framework

A short lowercase label, such as nextjs, saved with the app. The build does not read it: Railpack works out the framework from the files.

Dockerfile

A Dockerfile to build with, as a path inside the repository, such as docker/Dockerfile. Leave it empty to use a Dockerfile in the app's directory, or Railpack when there is none (Builds).

Install command, Build command and Start command

Commands that replace the ones Railpack would choose, up to 500 characters each. A Dockerfile build does not use them.

On the same card, and on the Name on the platform card of an image app:

Name on the platform

The app's unique name, such as web-shop, which its platform name web-shop.<app domain> is made from. It cannot change after you create the app (Names on the platform).

A name on the platform has 3 to 63 lowercase letters, digits and hyphens, and starts and ends with a letter or a digit. It cannot have hyphens in both its third and fourth places, and no other app on the platform can have it. Some words are reserved for the platform, such as api, admin, app, status and www.

When you leave it out, we make one from the app's name, such as web-shop for Web shop. When that one is taken or reserved, we add a hyphen and four random characters, as in web-shop-k3x9.

The dashboard confirms with a message such as Web shop created. and opens the first deployment's page, where the build log follows the build (Read a deployment and its build log). With no first deployment, it opens the app's Deployments tab.

A git app starts with a build of its branch, then starts replicas. An image app starts replicas at once.

A git app also gets a push webhook, and its secret is shown once. In the dashboard, the Push webhook secret dialog shows it with the Payload URL: copy both, or select Copy all, then select I have saved it. Through the API, the secret is in the answer to the request that creates the app. Save it if you want pushes to deploy the app (Deploy on every push). The Settings tab keeps the address and the secret's last four characters, and you can make a new secret there later.

If the first deployment cannot start, we still create the app and say why. The app's page shows The first deployment did not start with the reason and a Deploy… button. Fix the cause, then deploy it (Deploy an app).

The app is in the Apps list with its platform address, and its first deployment is on its way unless you turned it off. Once that deployment is Ready, the app is Live and answers at https://<name on the platform>.<app domain>.

The name web-shop is taken on the platform. Choose another

Another app has that name on the platform. Choose another, or leave it empty so that we make one.

www is reserved. Choose another name

The name is one the platform keeps for itself. Choose another.

Your account has as many apps as it may or The limit is 20 apps. Delete one before creating another

You have as many apps as you may, so New app… and Create app are turned off. Delete one you no longer need (Change or delete an app).

The repository must be on a public host. or The repository URL must start with https://.

Give the repository's HTTPS address on a public host.

Put the access token in the app's repository token, not in the URL.

Remove the user name or token from the address and put the token in Access token.

The image must be on a public registry

The image's registry is on a private network. Push the image to a public registry.

These regions cannot run apps: syd

The regions named cannot run apps now. Choose from the regions the platform offers, or choose every region.

Too many apps created in the last hour. Wait a while and try again.

You created 20 apps in the last hour. Wait, then try again.

Could not load the regions

The page could not read the regions and sizes it offers. Select Try again.

• How Apps works
• Deploy an app
• Set environment variables
• Add a custom domain

POST /api/v1/client/apps creates an app of your own. For an organization's app, send the same body to POST /api/v1/orgs/{org_slug}/apps.

curl -X POST https://api.coritan.com/api/v1/client/apps \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web shop",
    "source_type": "git",
    "repo_url": "https://github.com/example/web-shop",
    "repo_branch": "main",
    "repo_token": "github_pat_EXAMPLE",
    "health_check_path": "/healthz",
    "instance_size": "small",
    "regions": ["fra", "iad"],
    "min_replicas": 2,
    "env": [{"key": "DATABASE_URL", "value": "postgres://app:secret@db.example.com/shop"}]
  }'

The body takes these fields. Only name is required, and a git app also needs repo_url, an image app image_ref.

name

1–100 characters.

slug

The name on the platform. Made from name when left out.

source_type

git, the default, or image.

repo_url, repo_branch, repo_subdir and repo_token

A git app's repository, branch (main when left out), directory and access token. An image app refuses them.

image_ref

An image app's image reference. A git app refuses it.

dockerfile_path, install_command, build_command, start_command and framework

How a git app builds and starts.

port and health_check_path

3000 and / when left out.

instance_size

small, medium or large. small when left out.

regions

["*"] for every region, the default, or a list of up to 20 region codes.

min_replicas and max_replicas

Replicas in each region, 1–5 for min_replicas (1 when left out). max_replicas takes up to 10, and one below min_replicas is raised to it.

env

A list of variables, each with key, value and optionally secret and target (Set environment variables).

deploy

true, the default, starts the first deployment. false creates the app without one.

It answers 201:

{
  "app": {
    "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "name": "Web shop",
    "slug": "web-shop",
    "status": "active",
    "source_type": "git",
    "repo_token_set": true,
    "repo_token_hint": "MPLE",
    "url": "https://web-shop.apps.example.net"
  },
  "deployment": {
    "uuid": "0b6f3d2e-7a41-4c59-8e1d-2f9a6b3c4d5e",
    "status": "queued",
    "source": "git",
    "trigger": "manual",
    "git_ref": "main"
  },
  "deploy_error": null,
  "webhook": {
    "url": "https://api.coritan.com/api/v1/apps/hooks/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "secret": "4f1d2c3b5a69788796a5b4c3d2e1f0a94f1d2c3b5a69788796a5b4c3d2e1f0a9"
  }
}

The example shortens app and deployment, which carry every field (App and deployment fields). webhook.secret appears in this answer only, and webhook is null for an image app. deployment is null when you sent "deploy": false, and also when the first deployment could not start, when deploy_error says why, as in Builds are not available on this platform yet.

An organization's route also answers 403 with Admin access required for a member who is not an owner or admin. Apps limits lists the other rate limits.