application · containers · devops

Command your containers,Portainer.

A visual backend panel for containerized infrastructure — deploy, monitor, and scale workloads across Docker, Docker Swarm, and Kubernetes from one dashboard. This guide covers installation with Compose and the CLI, Swarm and Kubernetes agents, Edge devices at scale, and safe upgrade strategies.

Docker installKubernetesEdge agentsUpgrades

One panel, every cluster

Portainer sits on top of the Docker socket or a Kubernetes namespace and turns container operations into a visual workflow — granular control without memorizing CLI commands.

• Docker — Compose or CLI install with a persistent volume.
• Kubernetes — official manifest into a portainer namespace.
• Edge — thousands of remote devices over outbound tunnels.

9443UI port

8000Edge tunnel

CE / BEEditions

portainer_dataData volume

FeaturesFAQRelated

On this page

What this guide covers

Docker

Compose and CLI deployment — persistent volume, socket mount, and the CE versus Business Edition choice.

Kubernetes

Namespace creation, the official manifest, and upgrading the Portainer agent inside a cluster.

Edge

EDGE_ID and EDGE_KEY setup with Consul, Terraform, and Ansible automation — scaling to 15000 devices.

Upgrades

Back up first, test in staging, and apply the right strategy for Docker, Swarm, or Kubernetes environments.

Start here

Information

Note

Portainer is a web-based container management software that helps maintain Docker and Kubernetes clusters within the eco-system.

This expert document covers the advanced configuration and deployment of Portainer across Docker, Docker Swarm, and Kubernetes environments. Portainer’s intuitive interface provides granular control over containerized infrastructure, making it a vital tool for DevOps professionals and system administrators. We’ll start by detailing the setup process for Docker, including best practices for connecting to remote Docker hosts and securing the Portainer instance. For Docker Swarm, we’ll explore strategies for managing multi-node clusters, handling service updates, and integrating external storage solutions. In the Kubernetes section, we’ll dive into deploying Portainer within a k8s cluster using Helm charts and managing complex workloads with namespaces and RBAC policies. We’ll also cover advanced monitoring configurations using Portainer’s agent and extensions to gain insights into resource usage and performance. Throughout this guide, you’ll find recommendations for optimizing container orchestration and maintaining high availability. Whether you’re managing a small development environment or a large-scale production system, this guide will provide the expertise needed to master Portainer’s capabilities.

Socket and volume

Docker

Portainer needs two things on Docker: a persistent volume for its own data, and access to the Docker socket so it can manage the engine. You can deploy it with Compose or the raw CLI.

Compose

The declarative option — save as docker-compose.yml and run docker compose up -d:

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Port 9443 serves the HTTPS UI; 8000 is the tunnel port used by Edge agents. The Docker socket mount is what lets Portainer see and control containers on the host.

Caution

Mounting /var/run/docker.sock grants Portainer root-equivalent control of the host. Restrict who can reach port 9443, and set a strong admin password on first login — the setup screen locks after a few minutes for security.

• For Docker Compose

• Docker CLI

  • Step by Step Docker Command Line

    • 1. Portainer will need a volume, portainer_data, to operate from.

      docker volume create portainer_data

    • 2. Option A - Community Edition

      • We will have docker pull and run the CE portainer.

        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

    • 3. Option B - Business Edition

      • BE is the premium commercial licensed version that unlocks all components within the enterprise suite.

        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-ee:latest

      • If you wish to run the BE/EE version of portainer, setup the CE first, register for the BE key / license and then upgrade.

      • Note: Portainer Business Edition requires a license key ahead of time. They may have a freemium option for up to 5 nodes.

Swarm

For Swarm upgrades, we recommend that you snapshot / backup the container, as well as, make sure everything is stable and up-to-date.

It is recommended that you check the current instances of portainer_portainer and portainer_agent.

For Community Edition, the documentation recommends these following commands:

docker pull portainer/portainer-ce:latest
docker service update --image portainer/portainer-ce:latest --publish-add 9443:9443 --force portainer_portainer

After that was successfully upgraded, then move towards upgrading the portainer agent to the latest version with these commands below:

docker pull portainer/agent:latest
docker service update --image portainer/agent:latest --force portainer_agent

Now that the control center has the updated portainer and portainer agent, go ahead and use portainer to update the agent across the swarms. To do this, you can manually update it via the shell

Cluster deploy

Kubernetes

• Step-by-Step Kubernetes Breakdown

  • 1. Create the namespace portainer using kubectl. Below is the example command.

        kubectl create namespace portainer

  • 2. Inside of the namespace,$portainer, use kubectl apply with the official manifest.

        kubectl apply -n portainer -f https://raw.githubusercontent.com/portainer/k8s/master/deploy/manifests/portainer/portainer.yaml

  • 3. The default location will be returned from the manifest, located at port 30777.

---

Kubernetes Agent Upgrade

The current method for upgrade Portainer Agent through AWX would be to execute these following commands:

sudo kubectl delete namespace portainer
sudo kubectl apply -n portainer -f https://downloads.portainer.io/ce2-16/portainer-agent-k8s-lb.yaml

This will delete the existing portainer agent (which would be under the namespace of portainer) and then re-deploy the newer ce2-16.

However these notes are for Portainer Agent 2.16.1 / 11/18/2022. We will update these once there is another major release.

Remote fleets

Edge

• Setup
  • From Portainer, you must obtain the EDGE_ID and EDGE_KEY , both will be used to help organize the {$EDGE_DEVICE} within the hybrid cloud.
  • For network automation within the {$EDGE_DEVICE} we recommend that you use Consul application from Hashicorp.
  • For service automation within the {$EDGE_DEVICE} we recommend that you use Terraform application from Hashicorp.
  • Finally, after establishing the automation, we use Ansible to execute commands to Terraform,Consul and Portainer.
• Scale
  • 15000 {$EDGE_DEVICE} with a polling frequency of 5 seconds will generate about 7 mbps of network traffic and require 4 CPUs to handle the encryption / tunnel load, according to Portainer.

Stay current

Upgrades

Upgrading Portainer ensures access to the latest features, security patches, and performance improvements. Before upgrading, always back up your Portainer data to prevent any potential loss. Depending on your environment (Docker, Swarm, or Kubernetes), different upgrade strategies may apply, such as using Docker Compose or Helm charts. It’s recommended to test upgrades in a staging environment before applying them to production. For detailed steps and best practices, refer to the Official Docs on upgrading Portainer.

Questions

Frequently asked

What is Portainer used for?

Portainer is a web-based management UI for containers. It gives a visual dashboard to deploy, monitor, and manage Docker, Docker Swarm, and Kubernetes environments without memorizing CLI commands, with role-based access control for teams.

What is the difference between Portainer CE and Business Edition?

Community Edition (CE) is free and open-source with core container management. Business Edition (BE/EE) is the commercial version that adds RBAC, registry management, and support. BE requires a license key, though a free tier covers up to a small number of nodes.

How do I install Portainer on Docker?

Create a portainer_data volume, then run the portainer/portainer-ce image with the Docker socket mounted at /var/run/docker.sock and ports 8000 and 9443 published. Portainer's UI is then reachable over HTTPS on port 9443.

What is a Portainer Edge agent?

The Edge agent connects remote or air-gapped Docker/Kubernetes hosts back to a central Portainer instance using an EDGE_ID and EDGE_KEY over an outbound tunnel. It lets one Portainer manage many distributed environments without exposing each host's API.

Keep exploring

Related applications

DockerThe container engine Portainer manages through the socket mount.KubernetesCluster orchestration that Portainer surfaces in a visual dashboard.ProxmoxThe virtualization layer many Portainer-managed hosts run on.