# Deployments and push to deploy

URL: https://docs.vaultpanel.net/guides/applications/deployments

> How VaultPanel deploys an app from Git in stages, rolls back to an earlier release, deploys on every push and reloads Node.js apps without downtime.

Each deployment clones your branch into a new release folder, installs and builds it there, then
switches the app to it and checks that it answers. The running release is never touched until the
new one is ready, and a release that fails its health check is switched back.

## Deploy

Click **Deploy now** on the app's **Deployments** tab. A deployment also runs when the app is
created (unless you untick **Deploy as soon as the app is set up**), and on every push when
[push to deploy](https://docs.vaultpanel.net/guides/applications/deployments#push-to-deploy) is on.

Only one change runs on an app at a time. While a deployment runs, the app shows as **deploying**,
and a second deployment is refused with `409 APPLICATION_BUSY` until it finishes.

## Stages

A deployment goes through these stages, in order. A failed deployment names the stage it stopped at.

| Stage | What happens |
| --- | --- |
| **Prepare** | The app's user and folders are checked or created. |
| **Fetch** | `git clone --depth 1` of the branch into `releases/<id>`. The commit hash, author and message are recorded. |
| **Install** | Dependencies are installed (see [Supported runtimes](https://docs.vaultpanel.net/guides/applications#supported-runtimes)), or your install command runs. |
| **Build** | Your build command runs, if there is one. |
| **Configure** | The environment and the PM2 process file are written. |
| **Start** | `current` switches to the new release and the app starts or restarts. |
| **Health check** | With a port, the app must answer on it within the health check time (30 seconds by default). Without a port, it must stay running. |

If anything fails before **Start**, the running release keeps running and the half-made release is
removed. If the health check fails and there was a previous release, the app switches back to it
and the deployment fails with `HEALTH_CHECK_FAILED`. A deployment can run for up to 30 minutes.

> **Tip:**
  A health check failure usually means the app does not listen on the `PORT` environment variable.
  Read the **Logs** tab's error log for the reason.

## Deployment history

![The Deployments tab of the app api: six deployments with their status, trigger, commit, release folder and duration; the newest is marked Live, one failed at the build stage, and older ones offer Roll back](https://docs.vaultpanel.net/screenshots/app-deployments-light.png)

The app's **Deployments** tab lists its deployments, newest first, with their commit, trigger and
status, and marks the live release **Live**. **Deployments** in the sidebar lists every deploy and
rollback of every app. Open one to see its full log.

| Trigger | Started by |
| --- | --- |
| `manual` | **Deploy now** or the API. |
| `create` | The first deployment when the app was created. |
| `webhook` | A push to the app's branch. |
| `rollback` | A rollback to an earlier release. |

Statuses are `queued`, `running`, `succeeded`, `failed` and `cancelled`.

## Roll back

The newest releases stay on the server (5 by default; **Releases to keep** in **Settings**, up to
20), always including the live and the previous one. To go back to one, click **Roll back** next to
it on the **Deployments** tab.

The app switches to that release and restarts with the current environment and start command.
Nothing is rebuilt, so a rollback takes seconds. It still runs the health check.

You can roll back only to a release that deployed successfully and is still on the server. A
release that was removed answers `409 RELEASE_NOT_FOUND`: deploy its commit again instead.

## Private repositories

Use the repository's SSH address (`git@github.com:you/app.git`) for a private repository. When the
app is set up, VaultPanel makes an Ed25519 deploy key for it in the app's `.ssh` folder.

### Create the app without deploying

Untick **Deploy as soon as the app is set up** when you create the app.

### Add the deploy key to the repository

Copy the public key from the **Deploy key** card on the app's **Settings** tab, and add it to the
repository as a read-only deploy key (on GitHub: **Settings > Deploy keys**).

### Deploy

Click **Deploy now**. Git connects with that key and trusts the Git host's key the first time it
sees it.

`https://` repositories are cloned without a key, so they must be public.

## Push to deploy

Push to deploy gives the app a webhook URL for GitHub, GitLab, Gitea, Forgejo or Bitbucket. Each
push to the app's branch deploys it; pushes to other branches are ignored.

### Turn it on

On the app's **Settings** tab, click **Turn on** on the **Push to deploy** card. Copy the
**Webhook URL** and the **Secret** now: they are shown only once.

The URL has the form `https://panel.example.com/api/v1/hooks/deploy/<token>`, built from the
panel's address, so the panel must be reachable from your Git host.

### Add the webhook to your repository

Add a webhook with that URL, content type `application/json`, and push events. Paste the secret
in its secret field:

| Git host | Where the secret goes |
| --- | --- |
| GitHub | **Secret** |
| GitLab | **Secret token** |
| Gitea, Forgejo | **Secret** |
| Bitbucket | **Secret** |

### Push

A push to the branch answers `202` and starts a deployment with the trigger `webhook`. Ping events
and events other than pushes answer `200` and do nothing.

### How requests are checked

The token in the URL finds the app, and the secret proves the request came from your Git host:

- GitHub, Gitea, Forgejo and Bitbucket sign the body with HMAC-SHA256. VaultPanel reads the
  signature from `X-Hub-Signature-256` (`sha256=<hex>`), `X-Gitea-Signature` or
  `X-Forgejo-Signature` (`<hex>`), or `X-Hub-Signature` when it starts with `sha256=`.
- GitLab sends the secret itself in `X-Gitlab-Token`.

A request without a valid signature answers `401 WEBHOOK_SIGNATURE_INVALID`, deploys nothing, and
is recorded in the audit log as `application.webhook_rejected`. The webhook endpoint accepts up to
30 calls a minute.

To replace a leaked URL or secret, click **Create a new URL**, then update the webhook in your Git
host. **Turn off** removes the webhook.

> **Warning:**
  A webhook turned on before VaultPanel signed webhooks shows **On, unsigned**: anyone with its URL
  can start a deployment. Click **Create a new URL** to get a secret.

## Zero-downtime reloads

Node.js apps can reload without dropping requests: deployments, restarts and saved settings start
the new version before stopping the old one, so the port keeps answering. This needs agent 0.32.0
or newer.

To use it:

1. Make the start command run a Node.js file directly, such as `node server.js`, not `npm start`.
   PM2 runs the app in cluster mode, which can only run a Node.js script. A program that is itself a
   Node.js script, such as `node_modules/.bin/next`, also works.
2. Tick **Zero-downtime reloads** on the **Settings** tab and save.
3. Click **Apply and restart** once, so the app starts in cluster mode.

A deployment then logs a reload instead of a restart. If the start command cannot run in cluster
mode, the deployment fails at the **Configure** stage and says why.

Running several copies of an app uses the same cluster mode. See
[Scaling apps](https://docs.vaultpanel.net/guides/applications/scaling).

## API

Deployments can be started and followed through the REST API, the SDK and the CLI:

```js
import { VaultPanel } from '@vaultpanel/sdk';

const panel = new VaultPanel({ baseUrl: 'https://panel.example.com', token: process.env.VAULTPANEL_TOKEN });
const { job } = await panel.applications.deploy(appId);
await panel.jobs.wait(job.id);
```

See [Applications API](https://docs.vaultpanel.net/api-reference/applications) and [CLI commands](https://docs.vaultpanel.net/cli/commands).
