Applications

Deployments and push to deploy

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.

Last updated

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 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.

StageWhat happens
PrepareThe app's user and folders are checked or created.
Fetchgit clone --depth 1 of the branch into releases/<id>. The commit hash, author and message are recorded.
InstallDependencies are installed (see Supported runtimes), or your install command runs.
BuildYour build command runs, if there is one.
ConfigureThe environment and the PM2 process file are written.
Startcurrent switches to the new release and the app starts or restarts.
Health checkWith 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.

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 backThe 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

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.

TriggerStarted by
manualDeploy now or the API.
createThe first deployment when the app was created.
webhookA push to the app's branch.
rollbackA 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 hostWhere the secret goes
GitHubSecret
GitLabSecret token
Gitea, ForgejoSecret
BitbucketSecret

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.

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.

API

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

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 and CLI commands.