Tasks

A task is a command run on a schedule inside the app’s running container. KamalCloud runs it with kamal app exec --primary --reuse: once, on the primary host, inside the container already running there.

Reusing the running container is the point. It has your environment, your secrets, your code and your database connection, exactly as the app has them.

Adding one

Environment → Tasks → Add. Give it a name, a command and a schedule.

Name      Nightly digest
Command   bin/rails digest:send
Schedule  every day at 6am

Schedules read like Solid Queue’s: a cron line, or plain English – every day at 3am, every monday at 7am, every 15 minutes. The next run time is worked out and shown, so you can see whether the schedule means what you think it means.

Runs

Every run is a record with a status, a log and a runtime. Run one by hand any time from the task page; a manual run is the same command by the same route.

A failed run fires the task.failed notification.

A run that comes due while the environment is deploying waits, trying again every 30 seconds, rather than touching the checkout under the deploy. A run fails straight away if the app’s runner is not ready.

Scheduled runs are dispatched in production only; a development install never runs them on its own. Running one by hand works everywhere.

Changing one

A task cannot be edited. To change its command or schedule, delete it and add a new one.

Where it runs

The primary host – the first host of the primary role. Not on every machine in the role, which is what you want for anything that must happen once: a nightly digest sent from three machines is three digests.

Before the first deploy

A task needs a running container to exec into. Before the environment’s first deploy there is nothing to run in, and a run will fail saying so.

What a task is not

It is not a deploy hook. Tasks run on their own schedule, not at the end of a deploy – put release-time work in your deploy.yml where Kamal already handles it.

It is not a cron daemon on the machine. Nothing is written to the host’s crontab; KamalCloud dispatches the run at the scheduled time and Kamal executes it.