> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# The deploy script

> The part of a deployment that is yours, and the settings around it.

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](/servers/php#the-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](/source-control#composer-credentials) resolve.                                                                     |

## What a new site starts with

```bash theme={null}
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](/sites/deployments#the-two-checks) 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.