# Running applications

URL: https://docs.vaultpanel.net/guides/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](https://docs.vaultpanel.net/guides/websites/git-deploy).

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

> **Note:**
  If the server is missing something, the **New application** form says what to install, and the
  API answers `409` with the code `SOFTWARE_MISSING`.

## 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.
- **`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

| 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](https://docs.vaultpanel.net/guides/applications/deployments) 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.

> **Tip:**
  Creating a database for the app can add its connection settings to the environment for you. See
  [MariaDB databases](https://docs.vaultpanel.net/guides/databases).

## 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](https://docs.vaultpanel.net/guides/websites/domains) and
[SSL certificates](https://docs.vaultpanel.net/guides/websites/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](https://docs.vaultpanel.net/guides/applications/deployments#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](https://docs.vaultpanel.net/guides/applications#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](https://docs.vaultpanel.net/guides/applications/deployments#zero-downtime-reloads). |
| **Resource limits** | CPU and memory caps. See [Scaling apps](https://docs.vaultpanel.net/guides/applications/scaling#resource-limits). |
| **Deploy key** | The public key to add to a private repository. See [Private repositories](https://docs.vaultpanel.net/guides/applications/deployments#private-repositories). |
| **Push to deploy** | A webhook that deploys on every push. See [Push to deploy](https://docs.vaultpanel.net/guides/applications/deployments#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](https://docs.vaultpanel.net/guides/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](https://docs.vaultpanel.net/guides/security/users-and-roles).
