How to Install Portainer Bussiness Editon on Docker Swarm Cluster (2025 Update)

Deploying a robust and secure container management solution is paramount for any modern infrastructure. Portainer, with its intuitive interface and powerful features, simplifies this process significantly. This article provides a detailed, step-by-step guide to deploying Portainer on a Docker Swarm environment, ensuring a smooth and efficient setup. We'll cover everything from prerequisites to verification, helping you establish a secure and manageable system for your containerized applications.

Before embarking on the deployment, ensure your environment meets the necessary criteria. This foundation guarantees a seamless integration and prevents potential compatibility issues. Critically, your system should have a working Docker installation—avoiding Snap packages on Ubuntu for optimal compatibility—and Swarm mode enabled with its overlay network functioning correctly. This network is essential for inter-node communication within your swarm cluster. Administrator (sudo) access on the swarm manager node is also required.

Portainer, by default, utilizes port 9443 for its user interface and, optionally, port 8000 for Edge compute features. Inter-node communication on port 9001 is crucial for a functioning swarm. If employing Portainer Business Edition, a valid license key is necessary. We assume your system meets the standard Portainer requirements; deviations might necessitate specific configurations or limit functionality. Further, access to Docker should be through Unix sockets (TCP is not supported within Docker Swarm). SELinux should be disabled, and Docker must be running as root (rootless Docker presents limitations and requires additional configuration). Lastly, for simplicity, this guide focuses on single-manager node swarms; multi-node deployments require additional considerations. Finally, ensure that DNS resolution works flawlessly across all nodes in your cluster.

The deployment process involves leveraging Docker Swarm's stack deployment functionality. This method efficiently deploys both the Portainer Server and Agent as services across your cluster, streamlining the management process. This deployment should only be performed once per environment, regardless of the number of nodes. Adding each node individually is redundant and inefficient, consuming unnecessary resources and potentially exceeding your license's node count.

The deployment starts by retrieving the necessary stack manifest file:

# Download the Portainer stack YAML file.  Overwrites existing file if present.
curl -L https://downloads.portainer.io/ee-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml
    

This command fetches the YAML file containing the service definitions for both the Portainer Server and Agent. The -L option follows redirects, ensuring you get the most up-to-date version. The -o option specifies the output file name. The file is crucial for deployment and configuration.

Next, deploy the stack using the downloaded YAML file:

# Deploy the Portainer stack using the downloaded YAML file.  'portainer' is the stack name.
docker stack deploy -c portainer-agent-stack.yml portainer
    

This command initiates the deployment. The -c option specifies the path to the YAML file, and portainer is the name given to the stack. This command will create and start the necessary containers for both the Portainer Server and the Agent across all nodes in the swarm.

By default, Portainer utilizes a self-signed SSL certificate for securing port 9443. While convenient for initial setup, for production environments, you should replace this with a trusted certificate. This can be done either during installation (by providing your own certificate) or afterward through the Portainer UI.

Once the deployment completes, verify the successful start of the Portainer Server and Agent containers using the docker ps command:

# List all running containers.  Verify Portainer Server and Agent are running.
docker ps
    

The output will show the running containers, including the Portainer Server and Agent. Look for containers with names similar to portainer_portainer and portainer_agent. If these are running and their status indicates "Up," then the deployment was successful.

The final step involves accessing the Portainer UI. Open a web browser and navigate to https://localhost:9443. Remember to replace localhost with the appropriate IP address or fully qualified domain name (FQDN) if accessing from a remote machine. You might need to adjust the port if you configured a different port during deployment.

The initial login will present you with the Portainer Server setup page. From here, you can configure your environment, add Docker hosts, and start managing your containers.

This comprehensive guide provides a robust method for deploying Portainer on your Docker Swarm. The detailed steps and explanations ensure a smooth and secure deployment, enabling you to efficiently manage your containerized applications. By following this guide, you establish a solid foundation for streamlined container orchestration and management. Remember to always prioritize security best practices, especially in production environments. Using a trusted SSL certificate and regularly updating Portainer are essential steps for maintaining a secure and reliable infrastructure.