Joining a new endpoint to Portainer

Joining a new endpoint to Portainer has some documentation, but I didn’t find it sufficient. The following comes from experience of joining fs-docker-02 to, so will be relevant to fedora, but the process is similar on other distributions.


The overall flow is:

  • Allow connections to the new host, on tcp 2375, from the portainer instance.
  • Make docker listen on 2375.
  • Tell portainer that the new hosts exists.

Allowing connections.

Fedora Server uses firewall-cmd to manage IPTables.
Depending on your system, you may have many zones; however, the easiest thing to do is to add the rule to your default zone, which you can find by running firewall-cmd --get-default-zone.

Then, find the IP of the host that portainer is running on; for this example we’ll use The command to allow port 2375 only for one IP is as follows:

firewall-cmd --permanent --zone=<defaultZone> --add-rich-rule='rule family="ipv4" source address="" port protocol="tcp" port="2375" accept'
firewall-cmd --reload

Making docker listen (Source).

Find and copy the ExecStart= line of your docker.service file. Then create a file at /etc/systemd/system/docker.service.d/startup_options.conf (you may have to create docker.service.d) with the following contents:

# /etc/systemd/system/docker.service.d/override.conf
ExecStart=<start line>

where is the line from docker.service, but with -H tcp:// after -H fd://.
Then run systemctl daemon-reload and systemctl restart docker.service. Docker should now be listening on tcp 2375.

Pointing Portainer at the new endpoint.

On the portainer interface, you can add new endpoints (in settings). When adding this on the freeside infrastructure, use the FQDN of the new host (EG


This isn’t truly secure, as there’s no TLS involved, which is possible to do. If the firewall broke and started allowing from any source to 2375, then there’d be issues. Really, the correct way of doing this is to set up TLS properly and connect through 2376.

Previously there was a section that said " use the ip address of the new host and not the hostname, as the hostname redirects to nginx"; this was due to DNS records being behind the infrastructure state. If the DNS is up to date, then an FQDN should work perfectly fine.

1 Like