Tenkai
Sign inStart for free
Skip to guide
Help center

Run a command before a deployment or a rollback

Give a web application pre-deploy commands for its database migrations and rollback commands to undo them, and know when each runs and what a failure does.

What the commands are for

A web application can run your commands before a new version starts, for work that must happen once per deployment whatever the number of replicas, such as database migrations. Both lists are optional:

  • Pre-deploy commands run before a Deployment starts its new version.
  • Rollback commands run before a Rollback starts the earlier version.

Each list holds up to 10 commands. Only a web application has them: for a worker that shares its code, give the commands to the web application and deploy it first.

Set the commands

Owners, admins and developers set them.

  1. Open the web application, then More actions and Change configuration….
  2. Under Deployment commands, fill Pre-deploy commands, Rollback commands, or both, one command per line.
  3. Choose Save.

A command is a program and its arguments, such as node ace migration:run --force or php artisan migrate --force. It runs without a shell, like an entrypoint: quote an argument that has spaces, and start with sh -c to expand a variable.

Commands run in order, top to bottom:

node ace migration:run --force
node ace db:seed

The next deployment or rollback uses what you saved; one already running keeps its commands.

What a deployment does with the pre-deploy commands

After preparing the image and before starting the candidate, Tenkai runs each command in its own container from the new image. The container gets the variables of the web application, its size and its environment network, so it reaches a bound managed service. It gets no PORT, no route and no HEALTHCHECK. The running version keeps serving meanwhile.

When every command exits with 0, the deployment continues. Each command runs once per deployment, not per replica. A command sees what the one before it wrote to the database, but not the files it wrote in its container (except for an application that keeps files).

The deployment logs start with the last 500 lines each command wrote.

What a rollback does with the rollback commands

Rollback commands run the same way, but from the image of the version you leave, since only it knows how to undo its own changes, such as its migrations.

Tenkai does not put a database back by itself: your rollback commands do, or a restore of a backup. Write the commands in reverse order of your pre-deploy commands. node ace migration:rollback undoes only the last batch: if the version you leave ran two batches, it undoes only the second.

When a command fails

A command fails when it exits with a code other than 0, when its container cannot start, or when it does not end in time. The commands after it do not run, no candidate starts, the running version keeps serving, and the deployment or rollback fails with:

  • … failed: the command exited with a non-zero code, or its container did not run to its end.
  • … did not end in time: it passed the time limit.
  • … could not run: Tenkai could not start it, for instance after losing the connection to the cluster.

Tenkai does not undo what the failed command or those before it already did. Make migrations safe to run again, or fix them and deploy again.

Each command has 30 minutes once its container runs, after up to 10 minutes to pull the image. The logs often show why it did not end, such as a migration waiting for a lock.

What your commands must accept

  • The old version still serves. Add columns and tables first, and remove old ones in a later deployment.
  • Room on the nodes. A command reserves the size of the web application next to the running version, and the nodes must also have room for every replica of the new version. Otherwise the deployment fails with Not enough free capacity before any command runs.
  • No secret in a command. Commands appear as written on the Configuration tab and in the deployment logs. Put passwords and tokens in a variable.
  • No command for a new configuration. Apply configuration and a relocation run no command.

An application that keeps files

For a web application that keeps files, each command runs on the node that holds the files, with its directories mounted, so it can migrate an SQLite database.

Tenkai stops the running version before the first command, so the application is down while the commands run. It copies the files first, so the node needs room for that copy. When a command or the new version fails, Tenkai puts the files back and starts the previous version.

If Tenkai restarts after a command ran, the deployment fails with Deployment interrupted after its commands and the files are put back as before. Deploy again.