Zum Inhalt springen
TutorialsContainerAnfänger

How to Install Portainer

Install Portainer CE on Docker for a web UI to manage containers, stacks, volumes and networks: setup, first stack, security hardening, remote agents and troubleshooting.

von HomeServersGuide TeamAktualisiert 3. November 20265 Min. Lesezeit

What you'll build

Portainer gives Docker a friendly web interface. Instead of memorising 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, and it's a good learning aid: every action shows you what is happening underneath.

This tutorial assumes Docker is already installed. If containers are new to you, read Docker basics first. Plan for 10 minutes.

Is Portainer right for you?

Portainer is great for visibility and day-to-day tasks: seeing which containers are running, reading logs, restarting something, or editing a stack. It is not a replacement for understanding Compose files. Many people use it alongside Compose files kept in a Git repository. If you prefer a lighter alternative, tools like Dockge manage Compose stacks stored as plain files on disk, which some people find easier to back up and version.

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:lts

The same thing as a Compose file:

services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
 
volumes:
  portainer_data:

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 (root-equivalent), so protect access carefully (see hardening below).
  • Port 9443 — Portainer's HTTPS UI with a self-signed certificate. Your browser will warn about it until you place a real certificate in front, for example through a reverse proxy.
  • The lts tag follows the long-term-support release line, which changes less often than the newest release. Pin a specific version if you want full control.

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, unique admin password; avoid the default username admin if you can.

Choose the local Docker environment when prompted, and you'll land on the dashboard. You will see containers, images, volumes and networks for the host.

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. Stacks can also be deployed from a Git repository, which keeps your configuration in version control and lets Portainer redeploy on changes. Use environment variables in the stack editor instead of hard-coding secrets; see Compose best practices.

Tip: Portainer shows containers started outside the UI as "limited" or unmanaged stacks. To manage them fully, redeploy them as stacks.

Step 5: Everyday tasks

  • Logs and console — open a container to read logs or start a shell without SSH.
  • Resource usage — the stats view shows CPU and memory per container.
  • Updates — pull a new image, then recreate the container or redeploy the stack. Back up the volumes first.
  • Cleanup — remove unused images and volumes from the Images and Volumes pages. Be careful with "unused" volumes: a stopped app's data volume looks unused.
  • Networks — create and inspect networks; see Docker networking explained.

Step 6: 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 or Tailscale. See the secure remote access guide.
  • Use a reverse proxy with a real certificate and, ideally, an extra authentication layer.
  • Create separate users and teams with limited roles instead of sharing the admin account, and enable two-factor or SSO if available in your edition.
  • Keep it updated — pull the latest image regularly.
  • Back up the portainer_data volume so you can rebuild quickly.
  • Consider whether you need the Docker socket mounted read-only or a socket proxy for extra safety.

Step 7: 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. Keep agent ports reachable only from the Portainer server, or use the Edge Agent for hosts that can't accept inbound connections.

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. If Portainer disappears tomorrow, your stacks should still work with docker compose.

Troubleshooting

  • Can't reach the UI — confirm the container is running (docker ps) and port 9443 isn't blocked by a firewall. Use https://, not http://.
  • "Timed out for security purposes" — restart the container and complete setup promptly.
  • Permission errors managing containers — verify the Docker socket is mounted correctly.
  • Browser certificate warning — expected with the self-signed certificate; use a reverse proxy with a valid certificate.
  • Stack fails to deploy — read the error message; a typo in YAML, a port already in use, or a missing environment variable are the usual causes.

Next steps

Pair Portainer with Uptime Kuma for monitoring and a deliberate update routine to keep your images current. Then deploy useful apps such as Jellyfin, Pi-hole or Nextcloud.

Verwandte Artikel

TutorialsContainerAnfänger

Docker unter Ubuntu installieren

Installiere Docker Engine und das Compose-Plugin aus dem offiziellen Docker-Repository auf Ubuntu Server, prüfe die Installation, starte deinen ersten Container und behebe typische Fehler.

4 Min. Lesezeit
AnleitungenContainerFortgeschritten

Docker Networking Explained for Home Servers

Bridge, host, macvlan and internal Docker networks explained: container DNS, publishing ports, reverse proxy patterns, firewall pitfalls and a troubleshooting checklist.

4 Min. Lesezeit
AnleitungenContainerFortgeschritten

Docker Compose Best Practices for Home Servers

Structure Compose stacks, volumes, networks, secrets, healthchecks, logging and updates so your home server stays clean, secure and easy to rebuild.

5 Min. Lesezeit