Setting up SSH commands

SSH commands let you run commands on your own server as part of a deployment.

Use them to:

• Run database migrations
• Clear application caches
• Restart processes or services
• Run your own deployment scripts

For example, a Laravel project might run the following command after publishing a new release:

php artisan migrate --force

Launchdeck can run SSH commands at three stages of a deployment: before transfer, after transfer, and after publish. For most projects, After publish is the most useful.

SSH commands are only available when using the (zero-downtime) SSH deployment strategy, as Launchdeck needs shell access to run commands on your server.

Formatting

SSH commands can be specified using the built-in editor within the SSH settings modal under the "servers" configuration section of a new or existing project.

Commands should be specified one per line, and will each be executed as an individual shell command - meaning if you rely on environment variables, make sure to concatenate your commands into a single line.

If you're doing complicated stuff, consider adding a shell script to your codebase and invoking that.

Types of SSH commands

There are three different types of SSH commands. While this offers the optimal amount of flexibility, you'll find that "After publish" is the most useful in the majority of situations.

Before transfer

When: Immediately before uploading a new release to your server

Working directory: <installation path>

Once the build automation step is completed within the Launchdeck infrastructure, the build is prepared to be sent to your server as a new release in the releases subfolder of the installation path.

You may use "Before transfer" SSH commands to run a command on your own server. Once the command completes, the new build will be uploaded (transferred) to your server.

After transfer

When: Immediately after the new release is placed on your server

Working directory: <installation path>/releases/<release identifier>

The packaged build is now available as a release on your server, with an automatically generated numerical identifier.

Any SSH commands you define under "After transfer" will be run with the newly uploaded release as the working directory.

After publish

When: Immediately after a new release has been "published" (made "live") on your server

Working directory: <installation path>/releases/<release identifier>

Once a new release is ready on your server, you can click "Publish" in your project overview to update the current symlink such that the new release is now live on your server. You may define "After publish" SSH commands to run immediately after publishing a new release.

"After publish" is the most commonly applicable type of SSH command.

Let's consider three real-life use cases:

• Running migrations: The database structure should reflect the application sourcecode as you receive visitors. Were we to run the migrations before publishing the site, the database structure might be ahead of the currently active version serving your visitors, causing problems.
• Clearing cache: Cache should only be cleared as soon as the latest version of your application is serving visitors. If the cache is cleared any sooner, it could be populated by an older version of your application before the latest version is actually published.
• Restarting a server process: Restarting the server process or preconfigured service (for example using PM2) only makes sense once the new application sources are available at the current symlink to which you've pointed your service specification.

Maintenance mode

When you're using an "After publish" SSH command to run migrations immediately after publishing a new version, you could imagine a scenario where a visitor hits your site before all migrations were applied successfully.

In order to prevent faulty responses (or even erroneous database writes), you could surround your "After publish" SSH commands with two commands respectively, namely one to enable, and one to disable maintenance mode. Here's an example of how to do that with Laravel:

php artisan down
php artisan db:migrate --force
php artisan up

Ready to deploy?

Use SSH commands for tasks that need to run on your destination server, such as database migrations, clearing caches or restarting services.

For tasks that don't require access to your server, use build automation instead.

Happy deploying!