Installing Portainer on Debian 12

This guide provides step-by-step instructions for setting up Portainer on a fresh Debian 12 installation.

Prerequisites

• A Debian 12 server
• User with sudo privileges
• Internet connection

Step 1: Update Your System

sudo apt update
sudo apt upgrade -y

Step 2: Install Docker Engine

Set up Docker’s apt repository

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install 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

# Add the repository to Apt sources
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Note for derivative distributions: If you use a derivative distribution such as Kali Linux, you may need to replace $(. /etc/os-release && echo "$VERSION_CODENAME") with the codename of the corresponding Debian release, such as bookworm.

Install Docker packages

# Install latest version
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Or install a specific version
# List available versions
# apt-cache madison docker-ce | awk '{ print $3 }'
# 
# Set version and install
# VERSION_STRING=5:28.0.4-1~debian.12~bookworm
# sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker installation

sudo docker run hello-world

Step 3: Post-installation steps

Enable and start Docker service

sudo systemctl enable docker
sudo systemctl start docker

Add your user to the docker group (to run Docker without sudo)

sudo usermod -aG docker $USER

Note: You’ll need to log out and back in for this change to take effect.

Step 4: Install Portainer

Create a volume for Portainer data

sudo docker volume create portainer_data

Deploy Portainer

sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Step 5: Access Portainer

After installation, access Portainer through your web browser at:

https://your-server-ip:9443

Troubleshooting

• If you cannot access Portainer, check your firewall settings to ensure ports 8000 and 9443 are open
• Verify Docker is running with sudo systemctl status docker
• Check Portainer container status with sudo docker ps