# Docker containers

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

> Run Docker images on your servers with safe defaults, published ports, volumes, environment variables and limits, and automatic rollback on updates.

VaultPanel runs Docker images from Docker Hub or another public registry on any connected server. It
builds every container itself from a few settings, so a container can never be privileged, use the
host's network or mount a folder of the host. When an update does not start, the old container comes
back.

## Set up Docker

Containers need agent 0.10.0 or newer. Go to **Containers** and choose the server:

- If Docker is not installed, **Install Docker** installs the system's `docker.io` package and
  starts it.
- If Docker is installed but stopped, **Start Docker** starts it and makes it start at boot.

A Docker that is already there, the snap one included, is used as it is. The card then shows how
many containers run, how many VaultPanel deployed, the number of images and Docker's data folder.

## Deploy a container

Click **Deploy a container**, then fill in:

| Field | What it does |
| --- | --- |
| **Server** | A server where Docker is running. |
| **Name** | 3 to 32 lowercase letters, digits and dashes, starting with a letter. Other containers reach it by this name. |
| **Image** | Such as `nginx:1.27`, `redis:7` or `ghcr.io/owner/app:tag`. |
| **Ports** | Up to 10. Each maps a port on the server to a port in the container, for TCP or UDP, reachable from **This server only** or **Public**. |
| **Volumes** | Up to 10. Each is a named volume mounted at a path in the container, optionally read-only. |
| **Environment variables** | Up to 100, kept encrypted. |
| **Restart** | **Unless stopped** (default), **Always**, **On failure** or **Never**. |
| **Health check (seconds)** | How long the new container must stay up before the deployment counts as done. 3 to 300, default 10. |
| **Memory limit (MB)** | 32 to 262,144. Empty for no limit. |
| **CPU limit (%)** | 5 to 6,400; 100 is one CPU core. Empty for no limit. |
| **Command** | Optional. The command to run instead of the image's own, as you would type it. It runs without a shell. |

VaultPanel pulls the image, creates the container on its own Docker network (`vaultpanel`), starts
it and watches it for the health check time. A container that stops, keeps restarting or, when the
image has its own health check, reports unhealthy fails the deployment. One that reports healthy
early counts as up straight away.

### Ports

| Reachable from | Address | Use it for |
| --- | --- | --- |
| **This server only** | `127.0.0.1` | A website in front of it (a reverse proxy) or another app on the server. |
| **Public** | `0.0.0.0` | Direct access from the internet. |

> **Public ports skip the firewall:**
  Docker opens public ports itself, even when the server's firewall has no rule for them. Anyone on
  the internet can reach them. Prefer **This server only** and a website in front.

### Volumes

A volume is the container's own Docker volume, named `vp-<container>-<volume>`. Data in volumes
survives updates and redeploys. Folders of the host are never mounted.

### Safe defaults

Every container VaultPanel deploys runs with:

- no privileged mode, no added capabilities or devices, and `no-new-privileges`;
- the `vaultpanel` Docker network instead of the host's network;
- log files capped at 3 files of 10 MB each;
- the labels `io.vaultpanel.managed` and `io.vaultpanel.id`.

## Update a container

Open the container and change its settings on the **Settings** tab, then click
**Save and redeploy**. Tick **Pull the image again** to get the newest image for the tag even when
the server already has it. **Redeploy** pulls and recreates the container with its current settings.

An update replaces the container safely:

1. The image is pulled when you asked for it or when the server does not have it yet.
2. The current container is stopped and set aside under another name.
3. The new container is created, started and watched for the health check time.
4. If it stays up, the old container is removed. Its volumes are kept.
5. If it does not, the new container is removed and the old one is started again.

Saving new environment variables works the same way: the old container keeps running if the new one
does not start.

## Start, stop and logs

**All containers** lists every container on the server, including ones VaultPanel did not deploy.
You can start, stop, restart, inspect, read the logs of and remove any of them, except the panel's
own MariaDB and Redis containers, which the panel and the agent refuse to stop, restart or remove.

The **Images** tab lists the server's images. **Pull image** downloads one; removing an image deletes
it from the server.

## Remove a container

On the container's page, click **Remove container**. The container and its record are deleted, and
its image stays on the server. Its volumes are kept unless you choose to delete them too, which
cannot be undone.

## Permissions

| Permission | Allows |
| --- | --- |
| `containers.read` | Seeing containers and images. |
| `containers.operate` | Starting, stopping and restarting containers. |
| `containers.logs` | Reading container logs. |
| `containers.manage` | Deploying, changing and removing containers, reading their environment variables, installing Docker and managing images. |

The built-in **developer** role can read, operate and read logs. See
[Users and roles](https://docs.vaultpanel.net/guides/security/users-and-roles) and the [Containers API](https://docs.vaultpanel.net/api-reference/containers).
