Add a remote Docker host in Portainer using the edge agent

Overview

The following article will cover the steps how to add a remote Docker host in Portainer using the edge agent. Portainer supports remote management of multiple Docker hosts and has features and multiple tools/methods how to achieve it. This post will focus on using the Portainer edge agent.

In order to add a remote Docker host in Portainer there some requirements:

  • Portainer Docker host(Portainer installed and running)
  • Remote host/instance/server with Docker installed and running as well(Install Docker on Debian/Ubuntu)
  • Portainer edge agent installed and running on the remote Docker host

Portainer egde agent?

Portainer edge agent is a Docker container, which acts as an Portainer agent/client on a remote Docker host in order to establish a connection between one and another add a remote Docker host in Portainer. The edge agent is used because of the simplicity when installing and connecting Portainer to a remote Docker host and also it’s a secure option as well since the agent encrypts all the traffic between the Portainer and the remote Docker host.

Add a remote Docker host in Portainer using the edge agent

Portainer edge agent configuration

Once you have everything prepared, first step is within the Portainer dashboard. From the Portainer dashboard, navigate to the “Environments” menu. From there, click on the button “Add environment“.

Add a remote Docker host in Portainer using the edge agent
Portainer dashboard

This menu will offer you multiple options to choose from how to add a remote Docker host. For this case select the second option “edge agent”.

Add a remote Docker host in Portainer using the edge agent
Edge agent configuration

Bellow there are a couple of environment details that are required for Portainer in order to add the remote docker host and the information it requires is a “name” for your remote docker host, that can be anything you would like.

The second field asks for the “Portainer server URL” . This field should be populated automatically by Portainer and by default, a Public IP address of the Portainer server(Docker host) will be entered there. If by chance it’s not present there, please provide a public IP address of your Portainer host(if you do not have a domain/running portainer under a domain).


The next is the poll frequency, that can be left as default. You want to change this number if you have numerous/multiple numbers of docker hosts in order to optimize the performance of the connection to remote hosts.

The last information is the metadata, the group and the tags(if you created these but are not necessary).


After you provided all the necessary information click on the button “Add environment” and it will direct you to another page, the edge agent configuration.

Find out the IP address of your Docker host

To find the IP address of your remote Docker, run the command “ip a”(This is the command that’ll work in most cases) . The result will look something like this(picture bellow):

Add a remote Docker host in Portainer using the edge agent
Remote Docker host IP address

In the picture above, the referred “Public IP” address of the remote Docker host is listed as number 2, the interface named “enp1s0” with the IP address of 192.168.122.222.

Deploying the Portainer edge agent container

In this menu portainer will ask what kind of remote docker host are you adding. As you can see there are multiple options(linux or windows, Kubernetes, Docker swarm or Docker standalone) but for this case we’re going to select the Linux host and click on the button docker stand-alone.
Also make sure to enable the option “Allow self-signed certs”.

Add a remote Docker host in Portainer using the edge agent
Edge agent deployment command

After you click on that it will generate a command which we will need to copy and paste on our remote docker host and that command is the docker container command to deploy the portainer edge agent.

Copy this command first and then go to your remote docker host and paste this command and run it. After the command is done and the edge agent container is running, then return to the Portainer dashboard and click on the button “Add environment” .

Double check and confirm the IP address of the remote Docker host was entered in the “Public IP” field. By “Public IP” it’s referred to the actual IP address of your remote Docker(not of the Docker container) .

You can also on this page adjust the metadata info for the remote host.

add a remote Docker host in Portainer using the edge agent
Remote Docker host confirmation

If successful, Portainer will not return any errors and it will redirect you to “Environments” page and there your new Docker host should be listed.

add a remote Docker host in Portainer using the edge agent
Portainer environments

To test if it’s working, return to the Portainer “Home” page and the new host should be listed there as well. You should be able to access it right away.

add a remote Docker host in Portainer using the edge agent
Portainer Docker hosts

Summary

To summarize the article – we showcased the steps how to add a remote Docker host in Portainer using the edge agent by configuring and deploying the Portainer edge agent on our remote Docker host.

Thank you for your time…

You may also like...

1 Response

  1. ALFRED says:

    Thanks for the article. It’s very hephfully. Everything was clear starting until the end.

Leave a Reply

Your email address will not be published.