Docker deploy

Run your own Dockerfile or a ready-made public image behind a domain, with health-checked zero-downtime releases, rollback, persistent paths with backups, logs and container isolation.

Updated Oct 9, 2026 · 11 min read

When an app does not fit the built-in runtimes (another language version, system libraries, a vendor's image), ZoPanel can run it as a container. It builds the Dockerfile from your repository, or starts a ready-made public image, publishes the container on 127.0.0.1 only and puts the website's nginx, SSL and firewall in front of it. For one-click apps such as n8n or Nextcloud, use the App Store instead; it does not need the permissions below.

Requirements

All of these must be true, otherwise the deployment is refused:

Enable custom containers once, as root:

sudo zopanel ctl feature enable custom-docker

This switch exists only on the server's command line, not in the web panel, so a stolen panel session cannot start arbitrary containers.

Deploy a Dockerfile from a repository

1. Open Websites → New website, choose Git deploy, enter the Repository URL, Branch and, if the Dockerfile is in a subfolder, the Root directory. Click Create website.
2. If the repository contains only a Dockerfile (no package.json, requirements.txt, go.mod…), it is detected as Dockerfile and built as a container.
3. If another framework is detected, the note "A Dockerfile was also found: switch the runtime to docker to build with it instead." appears. On the Deploy tab, turn Auto-detect off in Build & run, set Runtime to Dockerfile (the Type becomes Container (Dockerfile)) and click Save & deploy.

The build context is the root directory: the Dockerfile must be there, and it and .dockerignore must be regular files, not symbolic links. ZoPanel runs docker build --pull, so base images are refreshed on every build, and passes PORT as a build argument (declare ARG PORT if you need it). Install, build and start commands are not used in this mode: put them in the Dockerfile. A build that runs longer than 45 minutes is stopped and the deployment fails.

Deploy a ready-made image

1. Create a website (for example Node / Proxy) or open an existing one, and go to its Deploy tab.
2. Under Source, choose Ready-made Docker image.
3. Enter the Image, for example nginx:1.27 or ghcr.io/owner/app:1.2.0, and click Deploy.

Rules for images:

• Public images only (Docker Hub, GHCR or another public registry). Registries on localhost or an IP address are refused.
• Lowercase name, optional tag and digest (app@sha256:…), at most 255 characters.
• Pin a tag. Every deploy pulls the image again, so a moving tag such as latest can change between deploys.

ZoPanel turns the image into a release (a one-line Dockerfile FROM the image) so it gets the same health check, zero-downtime switch and rollback as a built Dockerfile.

Ports

The container must listen on one HTTP port. ZoPanel picks it in this order:

1. the PORT environment variable, if you set one;
2. the first EXPOSE in the Dockerfile (for an image, the first TCP port the image exposes);
3. 8080.

Inside the container, PORT is set to that port. Outside, it is published on 127.0.0.1:<internal port> (shown as Internal port on the Deploy tab) and nginx proxies the domain to it. Nothing else of the container is reachable from the internet.

FROM node:22-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build
ENV PORT=3000
EXPOSE 3000
USER node
CMD ["node", "server.js"]

The app inside should listen on 0.0.0.0:$PORT, not 127.0.0.1: inside a container, 127.0.0.1 is the container itself.

Environment variables

Add variables in the Environment variables card and click Save & redeploy. Up to 200 variables, single-line values. They are passed to the container at start through a root-only file, never on a command line.

• Values are passed literally. Do not wrap them in quotes (Paste .env removes surrounding quotes for you).
• At build time, a variable reaches the RUN steps only if the Dockerfile declares it with ARG (see below). The other variables exist only while the container runs.

Variables at build time

When the Dockerfile declares ARG NAME (or ARG NAME=default) and a variable NAME is set in the panel, ZoPanel passes it to docker build as a build argument. The task log lists the names passed (Build arguments from the environment variables: …), never the values.

FROM node:22-alpine AS build
ARG NEXT_PUBLIC_API_URL
WORKDIR /app
COPY . .
RUN npm ci && npm run build

• Only declared names are passed, so other variables (database passwords, API keys) are never built into the image.
• Build argument values are visible in the image history: docker history shows them for every RUN step after the ARG, and anything a step writes with them stays in that layer. Do not declare secrets as ARG; read them at runtime from the environment instead. Use ARG for public settings such as a public API URL or a feature flag.
• The value of a declared ARG without a panel variable is its default in the Dockerfile.
• Names that would change how the server's docker command runs are never passed, for example PATH, HOME, LD_*, DOCKER_*, BUILDKIT_*, GO*, SSL_* and the proxy variables (HTTP_PROXY…). The task log lists the ones skipped. PORT is always the container's port.

Health check and zero-downtime releases

Each release starts in a second container on the idle slot's port. It goes live when the Health check path (default /) answers with an HTTP status below 500 within 120 seconds. nginx then switches to the new container and the old one is removed a few seconds later. If the build fails, the container exits or never becomes healthy, the last 25 lines of its output are written to the task log and the running container keeps serving.

Rollback

The Releases card keeps the last 5 releases, and each keeps its built image. Rollback starts the chosen image in the idle slot, waits for the health check and switches, without rebuilding. Images of older releases are deleted with their release.

Logs and controls

• Application output shows the last 400 lines of the container's output with timestamps; turn on Live to follow it. Docker rotates container logs (3 files of 10 MB).
• The status card shows the container's state, RAM and Internal port. Restart, stop and start act on the running container.
• Each build log (docker build output) is in Tasks.

Limits and data

On servers where Docker uses the systemd cgroup driver (the default on Ubuntu 22.04/24.04 and Debian 12/13), the container also runs inside the account's resource group, so the package's limits apply too.

Builds

docker build runs in the Docker daemon, not as the account's Linux user. With the systemd cgroup driver, the containers of the build's RUN steps are placed in the account's resource group (--cgroup-parent), so the package's CPU and memory limits apply to builds as they do to the running app: a step that needs more memory than the package allows is stopped (Killed in the task log). This works with BuildKit (Docker's buildx component) and with the older builder Docker uses when buildx is not installed. Not covered by the package limits:

• pulling base images, sending the build context and exporting the image, which the Docker daemon does itself;
• the disk space of images and the build cache (under /var/lib/docker, not in the account's quota).

Every build is stopped after 45 minutes.

Persistent paths

A container's filesystem is recreated on every deploy and rollback, so anything written inside it is lost, except in its persistent paths. On the Deploy tab, in Build & run, enter them in Persistent paths (in the container), comma-separated, then click Save & deploy:

/app/data, /app/uploads

• Each is an absolute folder inside the container, at most 10. Use only letters, digits, ., _, - and /; no .., no folder inside another one in the list.
• System folders are refused: /proc, /sys, /dev, /etc, /run, /boot, /bin, /sbin, /lib*, /usr/bin, /usr/sbin, /usr/lib* and everything inside them, and /, /usr, /usr/local, /usr/share, /usr/src, /var, /var/lib, /var/cache, /var/log, /home, /opt, /root, /tmp, /mnt and /media themselves (a folder inside them, such as /var/lib/postgresql/data or /usr/src/app/uploads, is fine).
• Each path is a folder on the server under /var/lib/zopanel-apps/git-<user>-<domain>/, reachable only by root and by this website's containers. It is mounted at the same path in both release slots: during a deploy the old and the new container use it at the same time for a few seconds, which file-based databases such as SQLite handle.
• A new folder starts empty and hides whatever the image has at that path, so use a folder for data, not the folder of your code. It is owned by the image's USER when that is a numeric ID (USER 1000); when the image runs as root it belongs to root in the container; when USER is a name (USER node), the folder is writable by every user of the container. Existing data keeps its owners.
• Like App Store app data, it is not counted in the account's disk quota.
• The data stays when you change the paths. It is deleted with the website only when you choose to delete its files, and with the account.
• An account move recreates the paths on the new server, empty: copy the data yourself.

The folders can be backed up like the data of App Store apps: a Backups card appears on the Deploy tab once the app has persistent paths. Anyone who manages the website can back up now; administrators set the schedule (daily or weekly, number kept), restore and delete. A backup pauses the container for the time of the copy; a restore stops it, replaces the data and starts it again. Backups are kept in /var/backups/zopanel-apps/ on the server, apart from account backups.

For data shared with other services, a database on another server or object storage, such as ZoPanel's S3 storage published on a domain (reached over HTTPS on port 443), is still the better place.

Isolation

A customer's container runs code the server does not control, so ZoPanel confines it:

• Network: containers cannot open connections to private, shared, loopback or link-local addresses (including the cloud metadata service at 169.254.169.254), nor to other containers. On the server itself they reach only the public ports: web (80, 443), mail (25, 465, 587) and DNS. The server's MySQL, PostgreSQL, Redis and the panel are not reachable from a container. Image builds run under the same rules.
• Privileges: every Linux capability is dropped except CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID, NET_BIND_SERVICE and KILL; no-new-privileges is set; Docker's default seccomp and AppArmor profiles apply.
• User namespaces: root in the container maps to an unprivileged ID range on the host.
• No host access: no Docker socket, and no host folder other than the website's own persistent paths.

If these rules cannot be applied, ZoPanel does not build or start the container.

Troubleshooting

Related

• Git deploy
• App Store and S3 storage
• Packages and limits
• Security
• Dockerfile reference