Skip to content
How to install

Container apps

A container app runs one container from an image you build elsewhere. The panel pulls it by its digest, routes hosts and paths to it, gives it a database and mail when it asks, and replaces it behind a health check when a new image comes.

A container app's Overview tab: the image it runs, how it is updated, and its routes
  1. Open Sites and choose New site.
  2. Under Type, choose Container. Fill in the title and the slug, then choose Continue.
  3. On Image, enter the Image reference, such as ghcr.io/example/app:stable. For a private image, fill in Registry user and Registry token. Or choose Upload an archive and pick a docker save archive.
  4. On Settings, the Port is the one the image exposes unless you enter one. The Health path is what a deploy waits for, and may carry a query, such as /health?deep=1. Switch on Database if the app needs one, and add its Environment and Mounts.
  5. On Routes, say where the app answers. It starts with its dev hostname.
  6. Check the Review step and choose Create site.

An app with mounts is created stopped, because its mounts are empty until you fill them. Fill them on its Settings tab, then choose Start.

The New site wizard for a container app, on its Image step

Each route has a host, a path match, a scheme and an On switch. Any path takes the whole host. Starts with and Exactly take a path. A longer path wins over a shorter one.

  • A host no other site has becomes the app’s own. It gets its certificate and is listed among the app’s hosts. Point its DNS at the app’s server. While another app has a route on it, the app keeps it.
  • On the host of another site on the same server, a route takes a path, such as northwindbakery.example/api/orders. That path answers from the app, the rest from the site. A new or changed route there needs Full access. Starts with / is refused there: it would take the whole site.
  • HTTP and Both answer plain HTTP on port 80 without the redirect to HTTPS, as a payment provider’s webhook may need. The block list applies on port 80 too.

Save routes puts them in force at once. Nothing restarts. If Traefik refuses a route, the card says why.

A container app's routes: a host of its own, and three paths of a WordPress site's domain

Environment on the Settings tab holds its variables. A Secret is never shown again. Replace sets a new value, and only then can its name or Secret change. Saving recreates the container behind the health check.

The panel fills these placeholders at every start:

Placeholder Value
{{db.host}}, {{db.port}}, {{db.name}}, {{db.user}}, {{db.password}} The app’s database
{{mail.host}}, {{mail.port}}, {{mail.user}}, {{mail.password}} The mail relay, with the app’s own login
{{site.domain}} The app’s first host

A mount is a folder of files you give the app, such as a key or a certificate. Choose Upload beside it and pick a .tar.gz or .zip. A job unpacks it in place of what the mount held, as the app’s user, and restarts the app. With In backups off, a mount stays out of every backup and still moves with the app.

Taking a mount off removes its files once a new container without it has passed. A fill that is cut off halfway keeps both the old files and the new ones on the server, and its job log says where. Filling the mount again clears them.

Data folders under How it runs are kept across deploys and are in backups. Each VOLUME of the image is one, for as long as the image declares it. A VOLUME in the container’s own system folders, such as /usr, is not kept: the job log says so, and what the app writes there is lost at each deploy.

  • Deploy now on the Overview deploys what the reference names now.
  • New images under the tag decides what a new image does: Automatic deploys it, Ask first sends an email and offers Update, Pinned checks nothing. Both leave alone an image whose deploy failed, and one that a Roll back or a restore went back from, until the tag names a newer one.
  • A reference on another registry clears the registry login. Enter the new login with it and choose Save reference and login.
  • With Back up before updates on Ask each time, Deploy now, Update, Roll back and an upload ask first, with Back up first on for a live app.
  • The Deploy hook lets your CI start a deploy after a push. Choose Make token. The token is shown once. Send it in a header:
Terminal window
curl -fsS -X POST -H "X-WPL7-Deploy-Token: <token>" https://panel.example.com/api/hooks/app-deploy

An app that runs an uploaded image has no deploy hook.

The Deploys tab lists every deploy, and each restore that brought back another image. A failed deploy shows why, and with Manage access the new container’s last log lines. Roll back deploys an earlier image again.

A container app's Deploys tab: five deploys, the failed one opened on its last log lines

The Logs tab shows the container’s newest 1,000 lines. With Follow on, it reads them again every 2 seconds.

A deploy asks the registry which image the reference names and pulls it by its digest. It checks that the image is for the server’s platform and carries no Traefik or panel labels. It holds the app’s routes, so Traefik answers 503, and stops the old container with its Stop grace. It starts the new one and asks the health path every 2 seconds until it answers 2xx. Then it asks the deploy check once, if there is one, with the same wait of its own. The new container is kept only then. Otherwise the old one comes back, and an email says why. If the routes cannot be held, the deploy stops before anything changes.

A change under How it runs, Environment or Mounts recreates the container the same way, and a new user is saved only once the new container passes. A new port waits for the next start, deploy or recreate: the health check asks it first, then the port the app runs on, and keeps the one that answers. So a new image, or a new environment, that moves the app to another port goes in behind one health check. A Roll back also asks the port its deploy ran on, and a restore the backup’s.

The container runs as the image’s user, with no published port and no new privileges. The panel asks it on its own network, so the health check and the uptime check work with every route off.

Limit Value
Routes, variables 100 each
A variable’s value 32 KB
Mounts, data folders 20 each
Health check wait 5 to 600 seconds, 60 by default
Stop grace 0 to 300 seconds, 20 by default
Registry check Every 5 to 1,440 minutes, 15 by default
An uploaded image 8 GB
A mount’s archive 4 GB
Images kept per app 3, for Roll back
  • One container per app, and no builds on the server.
  • A deploy answers 503 while the container is replaced: the old one’s stop, up to its Stop grace, and the new one’s start.
  • Files the image has under a VOLUME are not copied into its data folder. The app starts with it empty.
  • A mount’s archive with a link, a special file, an absolute path or .. is refused.
  • An uploaded image is one image from docker save, podman or skopeo: files, folders and links only, at most 10,000 entries.
  • An upload that no deploy or mount takes is removed after a day.
  • An uploaded image cannot be rolled back to once it is gone from the server.
  • An image that names its user by name needs an /etc/passwd of at most 1 MB. Or give the user as numbers.
  • A Docker Hub image is checked against Docker Hub’s pull limits. Give it a login, or use another registry.
  • Run a command needs sh and timeout in the image.
  • An app has no request limits or custom rules, only the block list and attack detection.
  • An app is stopped while it moves, and its routes do not change meanwhile. An app with a path of another site’s domain does not move.
  • Plain HTTP needs the Traefik of this release on the server, and on the server a move goes to. Update that server first.
  • The uptime check starts a short-lived container every minute for each app.