Setting up atomic deployments

In DeployHQ, you can setup atomic deployments to your servers to ensure that there is zero downtime during the actual deployment process.

You'll be able to find out useful information about how the process works and how to set it up below.

How it works

When you first run an atomic deployment to your server, DeployHQ will prepare 3 directories within your deployment path:

releases
shared
cache (this will be created if you set up the cache strategy)

And one symlink:

current

That points to a folder within the releases directory, named as a timestamp from when you ran the associated deployment.

Your files will be uploaded to that directory, then once this process has finished, the current directory will be symlinked to that release. This is where your live app will be run from.

The current symlink will therefore look like so:

current -> releases/20190123120000

This will also happen in exactly the same way during any subsequent deployments, but because the symlink doesn't get created until after files are transferred, your site will continue to run in its previous state.

Additionally, if the deployment fails at any point before that time, the site will stay pointed to the last release, completely unaffected.

Setting up an atomic deployment

Prerequesities

To start using Atomic deployments, you'll need to add a new server to your project which supports SSH access, with the ability to run POSIX operations (for both copying, and symlinking to release directories).

Adding an atomic server

Just configure a new SSH server as normal, but then also enable the option for Zero-downtime deployments at the same time:

Zero-downtime option

And choose your atomic deployment strategy. You can read more about that further down this guide.

Finally, you'll be able to control how many releases are kept on your server. This is set to 3 by default (including the latest that is symlinked from current), but you can raise or lower the number as required.

Please note that each release will take up additional disk space on your server so we recommend keeping the number as low as possible.

Once you've added your server, you'll need to run a full deployment as normal on the first deployment, so that the correct directories are prepared and a full copy of your site is uploaded to it.

After that, only your changes will be uploaded but onto a new, full copy of the last release on every subsequent deployment.

Using Atomic deployments with server groups

Atomic deployments are fully supported for server groups too, and with this in mind, you can also now set up different deployment strategies when configuring a server group.

You'll see two options, sequential or parallel when you're setting up a group:

Sequential and parallel deployments

Sequential will deploy to each server in turn, whereas parallel will deploy to each server at the same time (up to 3 at once), ensuring that each step is completed on all servers before moving onto the next step.

Therefore, when using atomic deployments with a server group it is strongly recommended that you use the parallel strategy.

Atomic strategy

When you first configure your server, you'll see an option to set a "Atomic deployment strategy". This works one of two ways:

Copy previous release before uploading changes to new release

During each deployment, the last release directory will be copied to a new release directory, and all changes will be uploaded directly there. The current symlink will then be switched to the new release folder.

This means that any changes you make to the release directory outside of the deployment process will be copied over.

Upload changes to a cache directory and copy new release from there

During each deployment, a cache directory that contains a clean copy of your repository only will be updated with the latest changes from the deployment. This will then be copied across to a new release folder before the current symlink is switched.

This means that any changes you make to the release directory outside of the deployment will not be copied over.

Moving an existing site over to atomic deployments

To make the initial setup as smooth as possible, DeployHQ requires your deployment path to only contain shared, releases, cache and current with no other files or folders present when you first create an atomic server.

Therefore, if you're adding a server with existing files, we advise creating a brand new directory to house the new structure and running a deployment from scratch. Once you've uploaded everything to the new path and setup and shared files or directories, you can point your webserver to this new path, rather than the old path.