Setting up SSH commands

Whereas the build automation feature lets you configure commands that will run within the Launchdeck infrastructure in an isolated container (perfect for installing dependencies, bundling code, etc.), SSH commands allow you to specify commands to be executed on your own server before, during or after publishing a new version.

SSH commands are only available if you're using the (zero-downtime) SSH deployment "strategy" as we'll need shell access in order to run commands on your server.

SSH commands are useful in a variety of situations, including:

  • Automatically running migration scripts after deploying a new version
  • Clearing application cache(s) when a new version goes live
  • Restarting a server process or service after uploading the latest sources

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. Here's a quick overview:

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

Let's deploy!

Situations where you'll need to run something on your own server are often inevitable, and we hope this solution works well for you. Don't forget: a lot of stuff can be achieved using build automation, and we strongly recommend it for operations that don't require the context of your destination server.

Happy deploying!