How to Install Docker Portainer on Debian 12

Install Docker Portainer on Debian 12 with Docker Engine, private HTTPS access, persistent data, verification checks, and fixes for common setup errors.
A polished 3D server rack with glowing container blocks and a secure dashboard on a midnight-blue background.

Install Docker Portainer on Debian 12 and finish with a working Docker Engine plus a persistent Portainer CE dashboard in about ten minutes. The dashboard stays on a private server address and is opened from your computer through an SSH tunnel.

Prerequisites

  • A 64-bit Debian 12 (Bookworm) VPS with at least 2 GB of RAM and 10 GB of free disk space for images, containers, and Portainer data.
  • SSH access as root, or a regular user with working sudo privileges.
  • Outbound HTTPS access to Docker’s package repository and Docker Hub.
  • An SSH client on your local computer. You do not need a domain for the private tunnel used here; you need one only if you later publish Portainer behind a reverse proxy.
  • A VPSLake Linux VPS if you need a root-access Debian server for Docker workloads.

The commands below use sudo for a normal SSH user. If you are logged in as root, remove sudo but keep the command order.

Step 1: Confirm Debian 12 and update the host

Checking the release before adding a repository prevents APT from mixing Bookworm packages with another Debian release.

. /etc/os-release && printf 'ID=%s\nVERSION_ID=%s\nVERSION_CODENAME=%s\n' "$ID" "$VERSION_ID" "$VERSION_CODENAME"
uname -m
sudo apt-get update
sudo apt-get full-upgrade -y

The first command should report Debian 12 and bookworm; most VPSs use x86_64:

ID=debian
VERSION_ID="12"
VERSION_CODENAME=bookworm
x86_64

If the codename is not bookworm, stop and use instructions for the release actually installed on the server.

Step 2: Remove conflicting container packages

Debian’s docker.io, standalone containerd, and older Compose packages can conflict with Docker’s official Engine bundle, so remove only installed conflicts before adding the new repository.

dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' docker.io docker-compose docker-doc docker-buildx podman-docker containerd runc 2>/dev/null | awk '$1 ~ /^ii/ {print $2}' | xargs -r sudo apt-get remove -y

No output means there was nothing to remove. This does not erase Docker data under /var/lib/docker/, but do not remove runtime packages on an existing production host until you know which workloads depend on them.

Step 3: Add Docker’s signed Bookworm repository

Docker’s APT repository provides the Engine, CLI, containerd, Buildx, and Compose plugin as a coordinated set. This follows Docker’s official Debian installation method and stores the signing key in a dedicated keyring instead of the deprecated apt-key database.

sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: bookworm
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt-get update

Check for a candidate package before installing Docker:

apt-cache policy docker-ce | sed -n '1,8p'

The Candidate line should show a version from download.docker.com. Do not continue if APT reports a missing Release file or selects an Ubuntu source.

Step 4: Install and test Docker Engine

Installing Compose alongside the Engine leaves the server ready for stacks you may later create from Portainer.

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo systemctl is-active docker
sudo systemctl is-enabled docker
sudo docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
sudo docker compose version

Expected output has an active, enabled service and version values that vary with Docker’s current stable packages:

active
enabled
Client x.y.z / Server x.y.z
Docker Compose version v2.x.y

Run Docker’s disposable test image. It verifies the daemon, registry access, and container runtime without leaving a stopped test container:

sudo docker run --rm hello-world

The final message should include Hello from Docker! and Your installation appears to be working correctly.

Step 5: Create Portainer’s persistent storage

A named volume keeps Portainer’s users, settings, and environment records outside the container so recreating the container does not reset the dashboard.

sudo docker volume create portainer_data
sudo docker volume ls --filter name=portainer_data

Expected output includes the volume name:

DRIVER    VOLUME NAME
local     portainer_data

Step 6: Deploy Portainer CE on a private HTTPS port

Portainer’s HTTPS interface uses port 9443. Binding the host side to 127.0.0.1 means it is reachable through SSH but not directly from the public network, so you do not need to open a new UFW rule.

The command uses Portainer’s long-term-support image, mounts the Docker socket for local Engine management, and omits port 8000 because Edge Agent features are not needed for this single-host setup. Portainer documents this container arrangement in its official Docker installation guide.

sudo docker run -d \
  --name portainer \
  --restart=always \
  --publish 127.0.0.1:9443:9443 \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume portainer_data:/data \
  portainer/portainer-ce:lts

Confirm the container is running and the published address is loopback-only:

sudo docker ps --filter name=portainer --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
NAMES      IMAGE                       STATUS      PORTS
portainer  portainer/portainer-ce:lts Up ...       127.0.0.1:9443->9443/tcp

Portainer generates a self-signed certificate initially, so a browser warning is normal when you first connect through the tunnel.

Step 7: Open the Portainer dashboard through SSH

An SSH local forward carries your browser traffic to the private listener without exposing the administration UI in the VPS firewall.

Run this command on your local computer, not in the VPS shell. Replace YOUR_SSH_USER with the login name and SERVER_IP with the public VPS address; leave the terminal open:

ssh -N -L 9443:127.0.0.1:9443 YOUR_SSH_USER@SERVER_IP

Browse to https://127.0.0.1:9443. Create the first administrator with a unique password of at least 12 characters, then select the automatically detected local Docker environment. The first Portainer account has administrator privileges.

If port 9443 is already occupied on your computer, change only the local side of the tunnel:

ssh -N -L 19443:127.0.0.1:9443 YOUR_SSH_USER@SERVER_IP

Use https://127.0.0.1:19443 in that case. The VPS still listens privately on 9443.

Verify Docker and Portainer

Run these checks on the VPS to prove that Docker starts at boot, Portainer has its restart policy, the listener is private, and HTTPS responds:

sudo systemctl is-active docker
sudo systemctl is-enabled docker
sudo docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' portainer
sudo ss -lntp | grep '127.0.0.1:9443'
curl --insecure --silent --show-error --output /dev/null --write-out '%{http_code}\n' https://127.0.0.1:9443

Expected results include:

active
enabled
always
LISTEN ... 127.0.0.1:9443 ...
200

Refresh the tunneled browser tab. You should see Portainer’s setup page or dashboard, and the local Docker environment should be available after the wizard completes.

Troubleshooting

Candidate: (none) for docker-ce

APT cannot see Docker’s Bookworm repository, or the source file has a typo. Inspect the source and refresh metadata:

cat /etc/apt/sources.list.d/docker.sources
sudo apt-get update
apt-cache policy docker-ce

The file should contain Suites: bookworm and the Docker signing key path. If apt-get update reports an expired or missing Release file, check DNS and outbound HTTPS before changing repository URLs.

permission denied while trying to connect to the Docker daemon socket

The Docker socket is root-owned, so use sudo as shown in this guide. If one trusted administrator should run Docker without sudo, add that account to the Docker group, then start a completely new SSH session:

sudo usermod -aG docker YOUR_SSH_USER

The docker group grants root-equivalent control of the host. Confirm the new session with id -nG; do not add ordinary application users.

bind: address already in use when starting Portainer

Another service already owns port 9443 on the VPS. Find it before changing the mapping:

sudo ss -lntp | grep ':9443'

If you need another private host port, remove the failed Portainer container and publish, for example, 127.0.0.1:19443:9443. Then tunnel to 127.0.0.1:19443 on the VPS and browse to the local port you chose.

Your Portainer instance has timed out for security purposes

Portainer stops an unconfigured instance when the first administrator is not created promptly. Restart it and complete setup immediately:

sudo docker restart portainer

Keep portainer_data mounted. Deleting that volume would remove the saved Portainer configuration and users.

Hardening

  • Keep Portainer bound to loopback. If you later need shared access, place it behind a reverse proxy with a trusted certificate, strong authentication, and a narrowly scoped firewall rule.
  • Treat the Docker socket and Portainer administrator account as root-equivalent access. Limit SSH keys and dashboard accounts to trusted operators.
  • Back up portainer_data before changing the image tag or recreating the container.
  • Review SSH exposure with VPSLake’s SSH hardening generator before relying on the tunnel as your only management path.
  • Docker-published ports can interact with firewall rules differently from ordinary host services. Keep this Portainer binding on loopback and review Docker’s firewall guidance before publishing application ports.

FAQ

Do I need a domain name for Portainer on Debian 12?

No. The SSH tunnel makes the dashboard available at https://127.0.0.1:9443 on your own computer. A domain becomes useful only for a deliberate public reverse-proxy deployment with trusted TLS.

Why is port 8000 not included?

Port 8000 is the optional Portainer tunnel used by Edge Agent features. A Portainer Server managing the Docker Engine on the same Debian host through /var/run/docker.sock can leave it unpublished.

Can I use UFW to expose port 9443 instead?

You can, but this guide does not need that exposure because the host binding is loopback-only. Keeping the UI private reduces its attack surface; if you publish it later, use HTTPS, a trusted certificate, strong authentication, and a narrowly scoped firewall rule.

How do I update Portainer without losing its configuration?

Keep the portainer_data volume, pull the new image, and recreate only the Portainer container with the same volume and socket mount. Back up the volume first and read the Portainer release notes for compatibility changes.

Samrat Ghosh
Written by

Samrat Ghosh

Founder & Infrastructure Engineer

Samrat Ghosh is the founder of VPSLake, where he builds and runs the remote desktop and VPS hosting infrastructure the company is built on. He writes hands-on guides about RDP, Windows Server, VPS management and secure remote access - the practical documentation he wishes had…

Previous Article

How to Install Docker Portainer on Debian 11

Next Article

Palworld Dedicated Server Requirements: RAM, CPU & Cost

Write a Comment

Leave a Comment

Your email address will not be published. Required fields are marked *

Subscribe to our Newsletter

Subscribe to our email newsletter to get the latest posts delivered right to your email.
Pure inspiration, zero spam ✨