Portainer Documentation
Official WebsiteKnowledge BasePricingGet 3 Nodes of BE Free
2.21 LTS
2.21 LTS
  • Welcome
  • What's new in version 2.21
  • Release Notes
  • Getting Started
    • Introduction
    • Portainer architecture
    • Lifecycle policy
    • Requirements and prerequisites
    • Install Portainer BE
      • Set up a new Portainer BE Server installation
        • Docker Standalone
          • Install Portainer BE with Docker on Linux
          • Install Portainer BE with Docker on WSL / Docker Desktop
          • Install Portainer BE with Docker on Windows Container Service
        • Docker Swarm
          • Install Portainer BE with Docker Swarm on Linux
          • Install Portainer BE with Docker Swarm on WSL / Docker Desktop
          • Install Portainer BE with Docker Swarm on Windows Container Service
        • Kubernetes
          • Install Portainer BE on your Kubernetes environment
          • Install Portainer BE with Kubernetes on WSL / Docker Desktop
        • Initial setup
    • Install Portainer CE
      • Set up a new Portainer CE Server installation
        • Docker Standalone
          • Install Portainer CE with Docker on Linux
          • Install Portainer CE with Docker on WSL / Docker Desktop
          • Install Portainer CE with Docker on Windows Container Service
        • Docker Swarm
          • Install Portainer CE with Docker Swarm on Linux
          • Install Portainer CE with Docker Swarm on WSL / Docker Desktop
          • Install Portainer CE with Docker Swarm on Windows Container Service
        • Kubernetes
          • Install Portainer CE on your Kubernetes environment
          • Install Portainer CE with Kubernetes on WSL / Docker Desktop
        • Initial setup
    • Add an environment to an existing installation
    • Updating Portainer
      • Updating on Docker Standalone
      • Updating on Docker Swarm
      • Updating on Kubernetes
      • Updating on Nomad
      • Updating the Edge Agent
      • Updating from Portainer 1.x
      • Switching to Portainer Business Edition
        • Upgrade to Business Edition from within Portainer Community Edition
        • Docker Standalone
        • Docker Swarm
        • Kubernetes
        • Upgrading Agent-only deployments
  • Using Portainer
    • Home
      • Snapshot browsing
      • OpenAMT
    • Docker/Swarm
      • Dashboard
      • Templates
        • Application
        • Custom templates
        • Deploy a stack
        • Deploy a container
      • Stacks
        • Add a new stack
        • Inspect or edit a stack
        • Create a template from a deployed stack
        • Webhooks
        • Migrate or duplicate a stack
        • Remove a stack
      • Services
        • Add a new service
        • Configure service options
        • Scale a service
        • View the status of a service task
        • View service logs
        • Roll back a service
        • Webhooks
      • Containers
        • Add a new container
        • View a container's details
        • Inspect a container
        • Edit or duplicate a container
        • Advanced container settings
        • Webhooks
        • Attach a volume to a container
        • View container logs
        • View container statistics
        • Access a container's console
        • Change container ownership
        • Remove a container
      • Images
        • Pull an image
        • Build a new image
        • Import an image
        • Export an image
      • Networks
        • Add a new network
        • Remove a network
      • Volumes
        • Add a new volume
        • Browse a volume
        • Remove a volume
      • Configs
        • Add a new config
        • Remove a config
      • Secrets
        • Add a new secret
        • Remove a secret
      • Events
      • Host
        • Details
        • Setup
        • Registries
      • Swarm
        • Details
        • Cluster visualizer
        • Setup
        • Registries
    • Kubernetes
      • Dashboard
      • kubectl shell
      • Kubeconfig
      • Custom Templates
        • Add a new custom template
        • Edit a custom template
        • Remove a custom template
      • Namespaces
        • Add a new namespace
        • Manage a namespace
        • Manage access to a namespace
        • Remove a namespace
      • Helm
      • Applications
        • Add a new application using a form
        • Add a new application using a manifest
        • Inspect an application
        • Inspect a Helm application
        • Edit an application
        • Webhooks
        • Detach a volume from an application
        • Remove an application
      • Networking
        • Services
        • Ingresses
          • Add an Ingress manually
          • Add an Ingress using a manifest
          • Remove an Ingress
      • ConfigMaps & Secrets
        • Add a ConfigMap
        • Add a Secret
      • Volumes
        • Inspect a volume
        • Remove a volume
      • More Resources
        • Service Accounts
        • Cluster Roles
        • Roles
      • Cluster
        • Details
        • Inspect a node
        • Setup
        • Security constraints
        • Registries
    • Azure ACI
      • Dashboard
      • Container instances
        • Add a new container
        • Remove a container
    • Nomad
    • Edge Compute
      • Edge Groups
      • Edge Stacks
        • Add a new Edge Stack
      • Edge Jobs
      • Edge Configurations
      • Waiting Room
      • Edge Templates
        • Application
        • Custom
    • Account settings
  • Administering Portainer
    • User-related
      • Users
      • Add a new user
      • Turn a user into an administrator
      • Reset a user's password
      • Teams
        • Add a new team
        • Add a user to a team
      • Roles
    • Environment-related
      • Environments
      • Add a new environment
        • Add a local environment
        • Add a Docker Standalone environment
          • Install Portainer Agent on Docker Standalone
          • Connect to the Docker API
          • Connect to the Docker Socket
          • Install Edge Agent Standard on Docker Standalone
          • Install Edge Agent Async on Docker Standalone
        • Add a Docker Swarm environment
          • Install Portainer Agent on Docker Swarm
          • Connect to the Docker API
          • Connect to the Docker Socket
          • Install Edge Agent Standard on Docker Swarm
          • Install Edge Agent Async on Docker Swarm
        • Add a Kubernetes environment
          • Install Portainer Agent on your Kubernetes environment
          • Install Edge Agent Standard on Kubernetes
          • Install Edge Agent Async on Kubernetes
          • Import an existing Kubernetes environment
        • Add an ACI environment
        • Add a Nomad environment
        • Provision KaaS Cluster
          • Civo
          • Akamai Connected Cloud
          • DigitalOcean
          • Google Cloud
          • AWS
          • Azure
        • Create a Kubernetes cluster
          • MicroK8s
            • Offline installation
        • Add an environment via the Portainer API
      • Auto onboarding
      • Groups
      • Tags
      • Manage access to environments
      • Manage access to environment groups
      • Update & Rollback
    • Registries
      • Add a new registry
        • Add a DockerHub account
        • Add an AWS ECR registry
        • Add a Quay.io registry
        • Add a ProGet registry
        • Add an Azure registry
        • Add a Gitlab registry
        • Add a GitHub registry
        • Add a custom registry
      • Browse a registry
      • Manage a registry
    • Licenses
    • Logs
      • Authentication
      • Activity
    • Notifications
    • Settings
      • General
      • Authentication
        • Authenticate via LDAP
        • Authenticate via Active Directory
        • Authenticate via OAuth
      • Shared credentials
        • Add Civo credentials
        • Add Akamai Connected Cloud credentials
        • Add DigitalOcean credentials
        • Add Google Cloud credentials
        • Add AWS credentials
        • Add Azure credentials
        • Add SSH credentials
      • Edge Compute
  • Frequently Asked Questions
    • Portainer Concepts
    • Installing
    • Upgrading
    • Troubleshooting
    • Contributing
  • Advanced Topics
    • CLI configuration options
    • App templates
      • Build and host your own app templates
      • App template JSON format
    • The Portainer Edge Agent
    • Access control
    • Reset the admin user's password
    • Security and compliance
    • Encrypting the Portainer database
    • Using your own SSL certificate with Portainer
    • Using mTLS with Portainer
    • Stream auth and activity logs to an external provider
    • Using Portainer with reverse proxies
      • Deploying Portainer behind Traefik Proxy
      • Deploying Portainer behind nginx reverse proxy
    • How Relative Path Support works in Portainer
    • Helm chart configuration options
    • Docker roles and permissions
    • Kubernetes roles and bindings
    • Deprecated and removed features
  • API
    • Accessing the Portainer API
    • API documentation
    • API usage examples
  • Get More Help
    • Knowledge Base
    • Portainer Academy
    • YouTube
    • GitHub
    • Slack
    • Discord
    • Open a support request
  • Contribute to Portainer
    • Contribute
    • Build instructions
      • Set up a macOS build environment
      • Set up a Linux build environment
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
  1. Administering Portainer
  2. Environment-related
  3. Add a new environment
  4. Add a Docker Swarm environment

Install Portainer Agent on Docker Swarm

PreviousAdd a Docker Swarm environmentNextConnect to the Docker API

Was this helpful?

Portainer uses the Portainer Agent container to communicate with the Portainer Server instance and provide access to the node's resources. This document will outline how to install the Portainer Agent on your environment and how to connect to it from your Portainer Server instance. If you do not have a working Portainer Server instance yet, please refer to the Portainer Server installation guide first.

In addition to the generic requirements for Docker Swarm environments, you will need:

  • The manager and worker nodes must be able to communicate with each other over port 9001. In addition, the Portainer Server installation must be able to reach the nodes on port 9001. If this is not possible, we advise looking at the Edge Agent instead.

  • If you are running Windows on your node, either:

    • Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2.

    • Windows Container Services (WCS) configured and running.

The Portainer Agent installation instructions also make the following additional assumptions about your environment:

  • SELinux is disabled on the machines running Docker.

  • You are accessing Docker via Unix sockets (or a named pipe when using WCS).

  • You have not set a custom AGENT_SECRET on your Portainer Server instance. If you have (by specifying an AGENT_SECRET environment variable when starting the Portainer Server container), you will need to provide that same secret to your agent in the same way (as an environment variable) when deploying by adding it to the stack file:

    environment:

    - AGENT_SECRET: yoursecret

From the menu expand Environment-related, click Environments, then click Add environment.

Only do this once for your environment, regardless of how many nodes are in the cluster. You do not need to add each node as an individual environment in Portainer. Adding just one node (we recommend the manager node) will allow Portainer to manage the entire cluster.

Next, select Docker Swarm as the environment type then click Start Wizard. Select the Agent option and your platform. Copy the command, then run it on the manager node of your Docker Swarm cluster. For example, if you are deploying on a Linux machine or a Windows machine with WSL installed, use the Linux & Windows WSL command. If you are deploying on a Windows machine with WCS, use the Windows WCS command.

You must run the command on the Docker Swarm cluster before entering the environment details.

--mount type=bind,src=//,dst=/host

If Docker on the environment you're deploying the Agent to has the Docker volume path at a non-standard location (instead of /var/lib/docker/volumes) you will need to adjust the volume mount in the deployment command to suit.

For example, if your volume path was /srv/data/docker, you would change the line in the command to:

--mount type=bind,src=//srv/data/docker,dst=/var/lib/docker/volumes \

The dst value of the mount should remain as /var/lib/docker/volumes, as that is what the Agent expects.

The deployment command will return something similar to this:

Creating network portainer-agent_portainer_agent
Creating service portainer-agent_agent

To validate the agent is running, run the following command:

 docker service ls

The result of which should look something like this:

ID                  NAME                    MODE                REPLICAS            IMAGE                    PORTS
tshb6ee2710s        portainer-agent_agent   global              1/1                 portainer/agent:latest

Once the agent is running on the Docker Swarm cluster, enter the environment details, using the table below as a guide.

Only do this once for your environment, regardless of how many nodes are in the cluster. You do not need to add each node as an individual environment in Portainer. Adding just one node (we recommend the manager node) will allow Portainer to manage the entire cluster.

Field
Overview

Name

Give the environment a descriptive name.

Environment address

Enter the IP or DNS name at which the Portainer Server instance can reach the environment along with the port (9001).

As an optional step you can expand the More settings section and categorize the environment by adding it to a group or tagging it for better searchability.

When you're ready, click Connect. If you have other environments to configure click Next to proceed, otherwise click Close to return to the list of environments.

If you want to use the of the Portainer Agent, you should add the necessary volume mount to the command that Portainer provides:

host management features