How to add a remote Portainer endpoint using the Portainter Agent.

Portainer is a handy web interface for managing Docker containers. If you manage several Docker hosts than it is useful to attach remote endpoints to a central Portainer container to enable easy access to all your Docker hosts and their containers.

There are a few ways to add a remote endpoint to Portainer. The easiest method I have found is using the Portainer agent. This requires adding a container to the remote Docker host. According to the documentation this also gets around some limitations of the Docker API.

Here is an example docker-compose.yml file:

version: 3

services:
  agent:
    image: portainer/agent:latest
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - /var/lib/docker/volumes:/var/lib/docker/volumes
  ports:
    - 9001:9001
  restart: unless-stopped

Once the Portainer agent is up and running go to the local a.k.a. central Portainer instance and...

1. Click on Endpoints
2. Click Add Endpoint
3. Select Agent (this is the default)
4. Enter the name (this can be whatever you want)
5. Enter Endpoint URL. (this is a bit misleading as it is not a URL, just the host ip or hostname and port. Note: specifying the port is important.
6. Enter Public IP. (again, this is a bit misleading as this can be the IP or hostname)
7. Click Add endpoint

I am not clear why it is necessary to enter the Endpoint URL and the Public IP. In my case both have been the same except for the addition of the network port on the Endpoint URL.

According to some forum posts by default the remote agent will only connect with the first connection, so it is only possible to connect each remote agent to one Portainer instance. I believe that the configuration can be tweaked to all the remote agent to connect to multiple Portainer instances, but if you do this then you need to implement another layer of authentication/security...otherwise anyone can connect to your Docker host via the Portainer agent.

If you central Portainer container loses its configuration and the remote agent, then it will not be possible to reconnect to the remote agent, but this is an easy fix...

1. Connect to remote host.
2. Stop agent container
3. Remove agent container
4. Remove agent image
5. Restart agent container

Once the agent container is restarted you should be able to reconnect from your local Portainer.