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
  • Async mode vs Standard mode
  • Preparation
  • Deploying

Was this helpful?

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

Install Edge Agent Async on Docker Standalone

PreviousInstall Edge Agent Standard on Docker StandaloneNextAdd a Docker Swarm environment

Was this helpful?

When a remote environment is not directly accessible from the Portainer Server instance, we recommend deploying the Portainer Edge Agent to the remote environment. This allows you to manage the remote environment from your Portainer Server instance without having to open any ports on the environment. Rather than the traditional approach of the server connecting to Agents, the Edge Agent instead polls the Portainer Server periodically to see if there are any pending jobs to perform, and acts appropriately.

For a technical summary of how the Edge Agent works, refer to our .

Async mode vs Standard mode

The Portainer Edge Agent can be deployed in two different modes - standard mode and async mode. In standard mode, we provide the ability to connect to the remote Edge Agent through a tunnel that is established on-demand from the Edge Agent to the Portainer Server, letting you interact directly with the environment in real time.

In async mode, this tunnel connectivity is not available. Instead, we provide the ability to browse snapshots of the remote environment, allowing you to see the state of the Edge Agent's environment based on a recent state capture sent through to the Portainer Server, as well as use this snapshot to perform actions on the remote environment.

Async mode has been developed to use very small amounts of data and as such is suitable for environments that have limited or intermittent connectivity as well as connections with limited data caps, for example mobile networks.

Edge Agent Async mode is only available in Portainer Business Edition.

Preparation

In async mode, the Edge Agent requires only the UI port (usually 9443 or 30779 on Kubernetes with NodePort) to be open on the Portainer server instance. The tunnel port is not required for async mode. Our installation instructions configure Portainer Server to listen on both ports by default, and you will need to ensure your firewalling provides external access to the UI port in order to proceed.

If your Portainer Server instance is deployed with TLS, the agent will use HTTPS for the connection it makes back to Portainer. However if your Portainer instance uses a self-signed certificate, the Edge Agent must be deployed with the -e EDGE_INSECURE_POLL=1 flag. If you do not deploy the Edge Agent with this flag, then the agent will not be able to communicate with the Portainer Server instance.

In addition, our instructions assume your environment meets . While Portainer may work with other configurations, it may require configuration changes or have limited functionality.

Deploying

To add an async Edge Agent to a Docker Standalone environment, from the menu expand Environment-related, click Environments, then click Add environment.

Select Docker Standalone then click Start Wizard. Then select the Edge Agent Async option. Enter the environment details using the table below as a guide.

Field
Overview

Name

Enter a name for your environment.

Portainer API server URL

Enter the URL and port of your Portainer Server instance as it will be seen from your Edge environment. If using a FQDN, ensure that DNS is properly configured to provide this.

When you're ready, click Create. If you are pre-staging your Edge Agent deployment, you can now retrieve the join token for use in your deployment.

Otherwise, complete the new fields that have appeared using the table below as a guide.

Field/Option
Overview

Environment variables

Enter a comma separated list of environment variables that will be sourced from the host where the agent is deployed and provided to the agent.

Allow self-signed certs

Toggle this on to allow self-signed certificates when the agent is connecting to Portainer via HTTPS.

Choose your platform (Linux or Windows), copy the generated command and run the command on your Edge environment to complete the installation.

If you have set a custom AGENT_SECRET on your Portainer Server instance (by specifying an AGENT_SECRET environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Edge Agent in the same way (as an environment variable) when deploying your Edge Agent, for example by adding the following to your docker run command: -e AGENT_SECRET=yoursecret

If Docker on the environment you're deploying the Edge 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:

- v /srv/data/docker:/var/lib/docker/volumes \

The right side of the mount should remain as /var/lib/docker/volumes, as that is what the Edge Agent expects.

If you have another Edge async environment of the same type to deploy you can click Add another environment to do so. Otherwise if you have any other environments to configure click Next to proceed, or click Close to return to the list of environments.

As an optional step you can expand the More settings section and adjust the Ping, Snapshot and Command intervals for the environment - this defines how often this Edge Agent will check in with the Portainer Server for status updates, snapshot updates and to see if there are new pending commands to run, respectively. The default for each is once a minute, but the defaults can be adjusted in the .

You can also categorize the environment by adding it to a or it for better searchability.

group
tagging
advanced documentation
our requirements
Edge Compute settings