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.
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
| Runtime | Dependencies | Default build command | Default start command |
|---|---|---|---|
| Node.js | npm ci --include=dev when there is a package-lock.json, otherwise npm install --include=dev | None | npm start |
| Python | A virtual environment in the release (.venv), then pip install -r requirements.txt | None | gunicorn app:app |
| Go | go mod download when there is a go.mod | go build -o app . | ./app |
| Ruby | bundle install --jobs 4, with gems in the release's vendor/bundle | None | bundle 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:
releases/holds one folder per deployment, named by the time it was made and a random suffix. The newest few are kept for rollbacks.currentpoints 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.envfile (mode 600) written from the app's environment variables.logs/holds the app's output and error logs..ssh/id_ed25519is 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
| Field | What it does |
|---|---|
| Server | The server the app runs on. It needs a connected agent. |
| Runtime | Node.js, Python, Go or Ruby. |
| Git repository | An 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. |
| Branch | The branch to deploy. Defaults to main. |
| App name | 3 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. |
| Port | The 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 command | The command that starts the app, run from the app's folder. Empty uses the runtime's default. |
| Domain, More domains | Optional. 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; $PORTand${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,USERandPM2_HOMEare 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:
| Setting | What it does |
|---|---|
| Git repository, Branch | Where the next deployment comes from. |
| Start command, Install command, Build command | See Commands. |
| Releases to keep | How 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 reloads | Node.js only. See Zero-downtime reloads. |
| Resource limits | CPU and memory caps. See Scaling apps. |
| Deploy key | The public key to add to a private repository. See Private repositories. |
| Push to deploy | A 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
| Permission | Allows |
|---|---|
applications.read | Seeing apps and deployments. |
applications.deploy | Deploying, rolling back, starting, stopping and restarting. |
applications.logs | Reading the app's logs. |
applications.manage | Creating, 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.
App installer
Install WordPress, Joomla, Drupal or Laravel in a PHP website in one step, with its database and admin account, from the official release checked on download.
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.