Importing an existing app

If you already deploy with Kamal by hand, KamalCloud can write down what is running rather than making you recreate it.

Imports → New. Pick a server KamalCloud can reach. It reads the machine’s containers and shows you what it found. Choose a service, then fill in the rest of the form: the app’s name, the runner, the environment name and branch, the git connection and repository (or a plain git URL), and whether to check out submodules.

What it reads

KamalCloud reads each Kamal container’s name, image, status, labels and mounts – nothing else. It does not read the containers’ environment variables. From that:

• The service, from Kamal’s own labels. It stays exactly what the containers say, because Kamal names volumes and proxy routes after it – changing it would strand both.
• The destination, which becomes the environment’s name unless you give another. A service deployed with no destination is imported as a bare environment.
• The roles, each of which becomes a host on that server
• The proxy hosts kamal-proxy already answers for. No hostname is invented: if the app never served one, it does not get one here
• The accessories alongside it, with their images and data directories – the two nobody can guess. Only a kind KamalCloud knows with a single data directory is adopted. Their user, database and password are the catalog’s defaults until you set them on the accessory itself

The import creates the app, the environment, its hosts, its domains and those accessories. It creates no variables and no volumes.

What it does not do

Nothing is booted, restarted, removed or deployed. An import creates records in KamalCloud and changes nothing on the machine. There is no import record kept afterwards: what you have is an app, and deleting it offers to leave the containers running.

After importing

You land on the environment’s Variables page, because that is what is missing. Before the first deploy:

• Variables and secrets. None were brought across. Add everything the container needs, including any secret your deploy.yml names – a missing one blocks the deploy.
• Accessory passwords. An accessory’s connection URL is built from its password secret, so set the password its container already answers to, and confirm the user and database names.
• Volumes. Add any the app mounts under Volumes, then give them a backup schedule.
• Domains. Whatever the proxy was already answering for is recorded. Add the rest.

Then deploy once and compare. The first KamalCloud deploy of an imported app is the moment to find out whether anything was reaching the container from outside the config.