Applications

Running applications

Deploy Node.js, Python, Go and Ruby apps from Git, run them under PM2 as their own Linux user, and give them a domain with SSL.

Last updated

VaultPanel deploys apps from a Git repository into release folders, keeps them running with PM2 under systemd, and puts NGINX in front of them when you give them a domain. Each app runs as its own Linux user, so one app cannot read another's files.

Supported runtimes

RuntimeDependenciesDefault build commandDefault start command
Node.jsnpm ci --include=dev when there is a package-lock.json, otherwise npm install --include=devNonenpm start
PythonA virtual environment in the release (.venv), then pip install -r requirements.txtNonegunicorn app:app
Gogo mod download when there is a go.modgo build -o app ../app
Rubybundle install --jobs 4, with gems in the release's vendor/bundleNonebundle exec puma -b tcp://127.0.0.1:$PORT

Your own install command replaces the default one. Go and Ruby apps need agent 0.32.0 or newer. Ruby apps run in production mode (RACK_ENV and RAILS_ENV are production; set your own values in the app's environment to change them), and Go apps get GIN_MODE=release.

PHP websites can also deploy from Git into releases. That is a website feature, described in Git deployments for websites.

Before you start

The server needs the tools apps use. Open the server's page and install them from the App runtime card:

  • Git to fetch the code, and PM2 to keep apps running (installed with npm next to the server's system-wide Node.js).
  • Python, Go or Ruby for apps in those languages.

Node.js apps and PM2 run on a system-wide Node.js, in /usr/local/bin or /usr/bin (the agent itself does not use Node.js). If Node.js on the server is installed in a home folder (for example with nvm), apps cannot use it: install Node.js system-wide.

How an app runs

Every app gets a Linux user named after the app and a home folder under /var/www:

current → releases/20261110093015-a1b2c3
ecosystem.json
.env
app-output.log
app-error.log
  • releases/ holds one folder per deployment, named by the time it was made and a random suffix. The newest few are kept for rollbacks.
  • current points at the live release. The process always runs from it, so a rollback only moves the link and restarts.
  • shared/ holds the PM2 process file and the .env file (mode 600) written from the app's environment variables.
  • logs/ holds the app's output and error logs.
  • .ssh/id_ed25519 is the app's deploy key for private repositories.

PM2 runs in the foreground of a systemd unit named pm2-<app>, as the app's user. systemd starts it at boot and restarts it if it stops. The unit is sandboxed: the app cannot see /home or /root, has its own /tmp, and cannot gain privileges or change kernel settings.

Install, build and start commands run as the app's user, never as root.

Create an app

Open the form

Go to Applications and click New application.

Fill in the app

FieldWhat it does
ServerThe server the app runs on. It needs a connected agent.
RuntimeNode.js, Python, Go or Ruby.
Git repositoryAn https:// URL for a public repository, or an SSH address such as git@github.com:you/app.git for a private one. Never put a password in the URL.
BranchThe branch to deploy. Defaults to main.
App name3 to 32 lowercase letters, digits and dashes, starting with a letter. It is also the Linux user and folder name, must differ from every other app and website on the server, and cannot be changed later.
PortThe port the app listens on, from 1024 to 65535. The app receives it as the PORT environment variable. Leave it empty for a worker without a web port.
Start commandThe command that starts the app, run from the app's folder. Empty uses the runtime's default.
Domain, More domainsOptional. NGINX forwards these domains to the app's port. An app with a domain needs a port.

The form suggests the first free port from 3000 up. Ports 3306, 5432, 6379, 11211 and 27017 are refused because databases and caches usually take them, and so is a port another app or website on the server already uses.

Add build commands and environment variables (optional)

Click Build commands and environment to set the Install command, the Build command and the Environment variables (one KEY=value per line, like a .env file).

Create it

Leave Deploy as soon as the app is set up ticked to deploy right away. Untick it to set the app up first, for example to add its deploy key to a private repository before the first deployment.

The panel then creates the app's user and folders, adds its website if you gave a domain, and runs the first deployment. Each step is a job you can follow in the drawer. See Deployments and push to deploy for what a deployment does.

Commands

Install, build and start commands run without a shell:

  • one command per line, up to 10 lines of 500 characters each; blank lines and lines starting with # are skipped;
  • arguments are split like a shell would, with quotes grouping words;
  • pipes, redirects, ;, &&, backticks and $(...) are not supported. Put anything more complex in a script in your repository;
  • $PORT and ${PORT} are replaced by the app's port.

The start command is a single line. A program it names is looked up in the release first (for example node_modules/.bin or the Python virtual environment), then on the server.

Environment variables

The Environment tab lists the app's variables. Edit them one by one, or click Edit as text to paste a .env file.

  • Values are stored encrypted in the panel and written to the server only for the app's user, in shared/.env.
  • Up to 100 variables. Names use letters, digits and underscores and cannot start with a digit. Values are up to 8,192 characters.
  • PORT, PATH, HOME, USER and PM2_HOME are set by VaultPanel and cannot be set by hand.
  • Opening the tab is recorded in the audit log, and so is every change (names only, never values).

Changes apply on the next deployment. To use them now, click Apply and restart on the Settings changed since the app started banner. The same banner appears when you change the start command, the port, the health check, the resource limits or the number of copies.

Domains and SSL

An app's domains are served by a website of the same name: an NGINX reverse proxy from the domains to the app's port. Add domains when you create the app, or later on its Domains tab (the app needs a port first). Domains, DNS checks and certificates are then managed on that website, exactly as for any other site. See Domains and SSL certificates.

Run, stop and restart

The Overview tab shows the PM2 process: its state, process ID, memory and restarts. Use Restart, Stop and Start to control it. The app restarts by itself if it crashes, and starts again when the server boots.

A Restart of a Node.js app with zero-downtime reloads on starts the new process before stopping the old one. See Zero-downtime reloads.

Logs

The Logs tab reads the app's output log (logs/app-output.log) or error log (logs/app-error.log) from the server: the last 200 lines by default, from 10 to 2,000.

Settings

The Settings tab holds:

SettingWhat it does
Git repository, BranchWhere the next deployment comes from.
Start command, Install command, Build commandSee Commands.
Releases to keepHow many releases stay on the server for rollbacks, from 1 to 20. Default 5. Older ones are removed after each deployment.
Health check (seconds)How long a new release has to start answering on its port, from 5 to 300. Default 30.
Zero-downtime reloadsNode.js only. See Zero-downtime reloads.
Resource limitsCPU and memory caps. See Scaling apps.
Deploy keyThe public key to add to a private repository. See Private repositories.
Push to deployA webhook that deploys on every push. See Push to deploy.

The repository, branch and build commands apply on the next deployment. The start command and port need a restart with the new settings.

Apps of hosting customers

A hosting customer's app goes on their account's server, counts against their plan, and is capped at the plan's CPU and memory per app. Each customer also has their own app ports, taken from 10000 to 19999: as many as their plan allows apps. Their apps can only listen on those ports, and no other app can take them, so the Port field becomes a list of the customer's free ports. See Hosting and billing.

Delete an app

On the Settings tab, click Delete app and type the app's name to confirm. The app stops, its PM2 service is removed, and so are its website, NGINX site and certificate if it has one.

Tick Also delete the files to delete the Linux user and its releases, logs and .env as well. This cannot be undone. The app's databases are always kept.

Permissions

PermissionAllows
applications.readSeeing apps and deployments.
applications.deployDeploying, rolling back, starting, stopping and restarting.
applications.logsReading the app's logs.
applications.manageCreating, changing and deleting apps, and their environment variables.

The built-in developer role can read, deploy and read logs; viewer can only read. See Users and roles.