Tested with Portainer CE 2.40.0 · Docker Compose v2 · verified

Updated: 2026-07-17

Portainer[1] is the reference web UI for managing Docker containers, Docker Compose stacks (the tool that defines and starts several containers from one YAML file), and Swarm or Kubernetes clusters from a single panel, and it installs with one compose.yaml file and two commands. CE edition 2.40 STS adds native Docker Compose v2 support, HTTPS enabled by default on port 9443, and a unified panel for Docker Engine, Swarm, Kubernetes, and ACI resources. The same guide is available in Spanish.

This guide installs Portainer CE with Docker Compose v2 on a modern Debian/Ubuntu server (Ubuntu 24.04 LTS / Debian 13 Trixie), using a compose.yaml file and the official docker compose plugin (no dash, bundled with Docker Engine 20.10+; it replaces the older standalone docker-compose binary).

Key takeaways

  • Use compose.yaml (no version: key) instead of the old docker-compose.yml with an explicit version.
  • Pin the image (portainer/portainer-ce:2.40.0) instead of :latest to prevent silent upgrades.
  • The named volume (portainer_data) simplifies backups and updates.
  • The Docker socket is mounted read-only (:ro): Portainer doesn’t need direct socket write access.
  • The first-access form expires in 5 minutes: have everything ready before opening the browser.

Prerequisites

Before starting, you need:

  • Server with Docker Engine 24+ installed (includes the docker compose plugin by default). See the official Docker docs for Debian[2] or Ubuntu[3].
  • sudo access or a user in the docker group.
  • Port 9443 free for the HTTPS UI and, optionally, 8000 for the Edge Agent Tunnel (the channel Portainer uses to manage remote agents without opening inbound ports on them).

Prepare compose.yaml

Create the working directory and configuration file:

mkdir -p ~/docker/portainer
cd ~/docker/portainer
nano compose.yaml

Recommended content:

services:
  portainer:
    image: portainer/portainer-ce:2.40.0
    container_name: portainer
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "9443:9443"   # UI HTTPS
      - "8000:8000"   # Edge Agent tunnel (opcional)
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - portainer_data:/data

volumes:
  portainer_data:

Differences from older guides worth knowing:

  • No version: key. The Compose Specification has ignored it since 2023; today it’s redundant and triggers warnings in some versions.
  • compose.yaml filename preferred over docker-compose.yml (both work, but the new one is the official standard).
  • Image pinned to 2.40.0, not :latest. Pinning prevents surprises from silent major upgrades when the host runs a pull.
  • Named volume (portainer_data) instead of a bind-mount. Managed by Docker directly and easier to back up with tools like restic[4] or docker cp.
  • Docker socket read-only (:ro). Portainer controls everything via API, it doesn’t need direct host socket write access.
Portainer CE admin panel showing the list of running Docker containers

Portainer CE admin panel showing the list of running Docker containers

Launch the container

With the compose.yaml file in place, start Portainer in the background:

docker compose up -d
docker compose ps

You’ll see a portainer container running and listening on 0.0.0.0:9443. If the docker compose command doesn’t exist, make sure you’re using Docker Engine 20.10+ with the integrated plugin, not the legacy docker-compose (with a dash, no longer actively maintained).

First access

Open in your browser:

https://<IP-or-domain>:9443

The first time it will ask you to create the admin user with a minimum 12-character password. The form expires 5 minutes after the container starts; if you take longer, restart with docker compose restart and come back.

Because the HTTPS certificate is self-signed on first install, your browser will warn about a “not private” connection. That’s normal: click “Advanced” then “Continue” to proceed. For production, place Portainer behind a reverse proxy such as Traefik (the proxy that routes HTTPS traffic across containers and renews certificates on its own) with Let’s Encrypt (see below).

Upgrading Portainer

Upgrading Portainer is safe because the portainer_data volume persists users, endpoints, and configuration across versions. The process has three steps: edit compose.yaml and change the image tag (for example from 2.40.0 to 2.41.0), pull the new image and recreate the container, and finally clean up the old image if you want to free disk space:

docker compose pull
docker compose up -d
docker image prune -f

The volume guarantees the upgrade doesn’t lose data. If something goes wrong, edit the tag back to the previous value and run docker compose up -d again. If you’d rather automate this step entirely, see how to install Watchtower, the tool that watches your images and recreates containers when a new version lands.

Exposing Portainer via Traefik (optional)

If you already have Traefik as ingress with the traefik_public network defined, add labels to the service and drop the port mapping. When Traefik terminates TLS for you, the internal port is 9000 (HTTP), not 9443:

services:
  portainer:
    image: portainer/portainer-ce:2.40.0
    restart: unless-stopped
    networks: [traefik_public]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - portainer_data:/data
    labels:
      - traefik.enable=true
      - traefik.http.routers.portainer.rule=Host(`portainer.example.com`)
      - traefik.http.routers.portainer.entrypoints=websecure
      - traefik.http.routers.portainer.tls.certresolver=letsencrypt
      - traefik.http.services.portainer.loadbalancer.server.port=9000
      - traefik.http.services.portainer.loadbalancer.server.scheme=http

networks:
  traefik_public:
    external: true

volumes:
  portainer_data:

With this configuration, Traefik manages the TLS certificate with Let’s Encrypt and Portainer is accessible at https://portainer.example.com without non-standard ports. The same pattern applies to any additional service you deploy; see how to install local MCP servers as an example of a complementary service.

FAQ

Does Portainer replace the Docker command line?

Not entirely. Portainer covers most of the day-to-day work (starting, stopping, inspecting logs, deploying stacks, managing volumes and networks) from the browser, but for fine-grained debugging or automated scripts you’ll still reach for docker and docker compose in a terminal. Both read the same socket, so changes made by one show up instantly in the other.

Is it safe to expose Portainer directly to the internet on port 9443?

It works, but it isn’t advisable long term: the first-access form expires in 5 minutes precisely to reduce that risk, and after setup you should add further authentication. The safer route is placing it behind a reverse proxy with valid TLS and, where possible, restricting access by IP or VPN instead of leaving it open to anyone.

Can I manage multiple Docker servers from a single Portainer instance?

Yes. Besides the local environment, Portainer connects to remote endpoints via the Edge Agent (a small container installed on each server that opens an outbound tunnel to your central Portainer) or via a direct TLS API, letting you administer several hosts, a Swarm cluster, or Kubernetes from the same panel.

Conclusion

The modern Portainer install with Compose v2 is simpler than guides from three years ago: a 15-line compose.yaml, a pinned version, HTTPS by default, and persistence in a named volume. For multi-node environments, Swarm, or Kubernetes, Portainer adds the same UI on top of the cluster endpoint without changing this guide’s deployment pattern.

What stays constant across versions:

  • Pin the image to control when you upgrade.
  • Use a named volume, not a bind-mount, for the /data folder.
  • Mount the socket read-only.
  • Put a TLS reverse proxy in front for production.

Sources: [1] Official Portainer CE documentation (Docker install)[5], [2] Official Docker Compose documentation[6], [3] Official Traefik documentation[7], [4] restic documentation[4].

Sources

  1. Portainer
  2. official Docker docs for Debian
  3. Ubuntu
  4. restic
  5. Official Portainer CE documentation (Docker install)
  6. Official Docker Compose documentation
  7. Official Traefik documentation

Route: Self-hosting with Docker: from zero to production