How to Install Portainer

What you'll build

Portainer gives Docker a friendly web interface. Instead of memorizing CLI flags, you get a dashboard to deploy stacks, inspect logs, manage volumes and networks, and see resource usage at a glance. It's one of the first things many people install on a new home server.

This tutorial assumes Docker is already installed. Plan for 10 minutes.

Step 1: Create a volume for Portainer's data

Portainer stores its settings and user database in a volume so they survive restarts and upgrades:

docker volume create portainer_data

Step 2: Run Portainer CE

docker run -d \
  --name portainer \
  --restart unless-stopped \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

A few things worth understanding:

• /var/run/docker.sock — this is how Portainer talks to Docker. Mounting the socket effectively gives Portainer full control of the host, so protect access carefully (see hardening below).
• Port 9443 — Portainer's HTTPS UI with a self-signed certificate. You'll replace that with a real certificate via a reverse proxy later.

Step 3: Create your admin account

Open https://your-server-ip:9443 within a few minutes of starting the container (Portainer locks initial setup if you wait too long, as a security measure — just restart the container if that happens). Set a strong admin password.

Choose the local Docker environment when prompted, and you'll land on the dashboard.

Step 4: Deploy your first stack

The best way to use Portainer is with Stacks — Portainer's name for Docker Compose files. Go to Stacks → Add stack, paste a Compose file, and deploy. For example, a simple web app:

services:
  whoami:
    image: traefik/whoami
    ports:
      - "8081:80"
    restart: unless-stopped

You now have a versioned, editable stack you can update from the UI.

Step 5: Harden it

Because Portainer controls Docker, treat it as a high-value target:

• Don't expose it to the internet. Keep it on your LAN or behind a VPN like WireGuard / Tailscale.
• Use a reverse proxy with a real certificate and, ideally, an extra authentication layer.
• Create separate users with limited roles instead of sharing the admin account.
• Keep it updated — pull the latest image regularly.

Step 6: Manage remote hosts (optional)

If you run more than one Docker host, install the Portainer Agent on the others and add them as environments. You then manage every host from one dashboard — handy for a growing homelab.

Portainer vs. plain Compose

Portainer is excellent for visibility and day-to-day tasks, but many people still keep their canonical Compose files in a Git repository for reproducibility. A good workflow: define stacks as files you can back up, and use Portainer to monitor, inspect logs, and make quick changes.

Troubleshooting

• Can't reach the UI — confirm the container is running (docker ps) and port 9443 isn't blocked by a firewall.
• "Timed out for security purposes" — restart the container and complete setup promptly.
• Permission errors managing containers — verify the Docker socket is mounted correctly.

Next steps

Pair Portainer with Uptime Kuma for monitoring and Watchtower or a manual update routine to keep your images current.