The deploy script

The deploy script is the application-specific half of a deployment. Cloning the repository, linking the shared paths and moving the symlink are the deployer’s job, not the script’s, so editing this cannot break the release mechanics.

Where it runs

Inside the new release, in the application directory, as the site’s own account — never as root. A deploy script is written by whoever owns the site and should not be able to touch the machine beyond it. It cannot reach the live release, because the symlink has not moved yet. A script that fails leaves the running site untouched. It stops at the first failure. Without that, a failed composer install would run on into the commands after it and the real error would end up buried under whatever they produce for want of a vendor directory.

What is in the environment

Variable	What it is
`SHIPWAYS_PHP`	The full path to this site’s PHP binary. Use it rather than `php`, which is the machine’s CLI default and may be a different version.
`SHIPWAYS_SITE`	The site’s domain.
`SHIPWAYS_SITE_PATH`	The site’s directory, holding `releases`, `shared` and `current`.
`SHIPWAYS_RELEASE`	The name of the release being built.
`SHIPWAYS_RELEASE_PATH`	The release directory — the whole checkout.
`SHIPWAYS_APP_PATH`	The application inside it, which is the working directory. The same thing for an ordinary repository, a subdirectory for a monorepo.
`SHIPWAYS_BRANCH`	The branch this deployment recorded when it was created, not whatever the site points at by now.
`SHIPWAYS_COMPOSER_HOME`	Where Composer’s `auth.json` is, so private packages resolve.

What a new site starts with

composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev

# A modern Laravel application renders nothing without its built assets.
# Skipping this is the most common reason a first deploy boots on the
# command line and then returns a 500 to an actual visitor.
if [ -f package.json ]; then
    npm ci --no-audit --no-fund
    npm run build
fi

if [ -f artisan ]; then
    $SHIPWAYS_PHP artisan migrate --force
    $SHIPWAYS_PHP artisan config:cache
    $SHIPWAYS_PHP artisan route:cache
    $SHIPWAYS_PHP artisan view:cache
fi

Health check

The path the HTTP check asks for after the switch. Anything under 500 counts as alive, and a release that fails it is put back. A Laravel application from version 11 has /up for exactly this. It is worth using: a site’s root can be a redirect or a login page, and neither says anything about whether the application booted. Left empty, the root is used.

Releases to keep

How many release directories stay on disk after a deploy. Older ones are removed, and stop being offered for rollback. Each one you keep is another full copy of the application, vendor and built assets included.

Shared between releases

One path per line, relative to the release. Each is moved out of the application and linked back in, so it survives a deploy. storage and .env are always shared and do not go here — a site that stopped sharing them would lose its uploads on the next deploy. The first deploy takes whatever the repository shipped, so a directory with something already in it does not become an empty one. Paths are relative to the application, not the top of the checkout, because a shared path is something the application keeps: public/uploads means the application’s public directory wherever the application sits.

Getting started

Servers

Sites

Processes

Data

Across the fleet

The deploy script

Where it runs

What is in the environment

What a new site starts with

Health check

Releases to keep

Shared between releases

​Where it runs

​What is in the environment

​What a new site starts with

​Health check

​Releases to keep

​Shared between releases

Where it runs

What is in the environment

What a new site starts with

Health check

Releases to keep

Shared between releases