Apps

An app is a repository deployed with Kamal, or an image installed from a template. It names three things:

• The git connection and repository it deploys from
• The runner it deploys from
• Its environments, each one a Kamal destination

What your repository needs

KamalCloud does not replace your Kamal config. It expects the one you already have:

config/deploy.yml — read for the shape of the app: the service name, the image, the roles it declares, proxy settings, builder settings. KamalCloud parses it without evaluating any ERB in it; the file is read for shape, never executed.

A Dockerfile, or whatever your deploy.yml builder points at.

That is all. If kamal deploy works from your laptop, it will work from a runner.

What KamalCloud writes

Next to your checkout on the runner, per environment:

• config/deploy.<environment>.yml — the destination file: hosts and roles, env vars, accessories, proxy hosts, published ports
• .kamal/secrets.<environment> — the secrets file, from the environment’s secret variables

Kamal merges the destination file over your deploy.yml. Anything KamalCloud does not set stays exactly as your repository says.

Roles

The roles your repository declares are the roles KamalCloud offers when you place hosts. A role your deploy.yml names with nothing placed against it would fall through to whatever the repository says – which after kamal init is a placeholder address belonging to somebody else. KamalCloud blocks a deploy in that state rather than letting it happen.

Several apps on one server

A server is not reserved for one app. Any number of apps and environments can place hosts on the same machine, and kamal-proxy routes each by its own hostname. A server’s Apps page lists what is deployed there. Raw ports are the exception: two environments on one machine cannot publish the same one.

Renaming

The service name follows the app’s name, and Kamal names volumes and proxy routes after the service. Renaming an app therefore strands whatever the old name owned. KamalCloud notices and says so on the environment page before you deploy into the problem.

Submodules

An app can be told to clone submodules. Off by default, because a submodule that needs its own credentials turns a clone into a puzzle.

Deleting

Deleting an app removes its environments. What that does to the machines depends on what you choose at the point of deleting: leave the containers running, or have Kamal remove them first. Backups already in buckets are not touched.

Nothing goes until its data is somewhere else. The first attempt to delete something holding data takes a farewell backup of every volume and dumpable accessory under it and refuses; the attempt after that goes through. The refusal tells you what it took and what it could not, so “no bucket configured” is a sentence rather than a silent success.