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.
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_dataStep 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:ltsThe 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
ltstag 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-stoppedYou 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_datavolume 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. Usehttps://, nothttp://. - "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
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.
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.
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.