Portainer Remote Host Management – TLS protected!

Portainer is an awesome free and open-source graphical user interface to manage Docker containers on a Linux Server. But did you know you can also use a single Portainer instance to manage a Portainer remote host as well? In this tutorial, I will show you how you can easily connect all your Docker servers to your main Portainer instance and manage them all in one single UI.

Adding Portainer Remote Host

In Portainer you can navigate on your host to the “Endpoint” section and add additional hosts. Because Portainer is very flexible and does many things, you also have different options to set it up. You can manage containers in different ways, depending on your environment and requirements.

The Docker API will connect to a remote server. It is working the same way like on local instances, just over the network. But you need to do it the right way, to avoid opening security holes on your server. Because if you just expose the Docker API to the public internet without any restrictions, you will get pretty quickly infected by malicious containers. Make sure you’re not exposing it to the public internet, and also set up proper TLS encryption AND verification.

I recommend you read the official instructions. This will teach you how to generate proper certificates, which will make sure that your connection is encrypted. And only a verified client can connect to your remote server and execute docker instructions. Here is a quick walk of what you need to do.

By the way, if you want to keep all your Docker containers automatically updated, check out my tutorial about Watchtower!

Generate Certificates for Portainer and the Remote Server

Create a Certificate Authority (CA)

openssl genrsa -aes256 -out ca-key.pem 4096

openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem

These commands will generate CA Certificate. We also need to create a passhrase to generate the public cert with our private key.

Generate a Server Certificate

openssl genrsa -out server-key.pem 4096

openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr

echo subjectAltName = DNS:$HOST,IP:$INTERNALIP1,IP:$INTERNALIP2 >> extfile.cnf

echo extendedKeyUsage = serverAuth >> extfile.cnf

openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -extfile extfile.cnf

Generate a Client Certificate

openssl genrsa -out key.pem 4096

openssl req -subj '/CN=$PORTAINERDNS' -new -key key.pem -out client.csr

echo extendedKeyUsage = clientAuth > extfile-client.cnf

openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out cert.pem -extfile extfile-client.cnf

Cleanup and Protect your Private Keys!

rm -v client.csr server.csr extfile.cnf extfile-client.cnf

chmod -v 0400 ca-key.pem key.pem server-key.pem

Protect these certs as you would protect your root password! Because this is what it means, anyone with a connection to your docker API has root access to your server.

Enable Docker API on your Remote Server

Create /etc/docker/daemon.json with the following settings and replace $INTERNALIP with your IP address of the remote server.

    "hosts": ["unix:///var/run/docker.sock", "tcp://$INTERNALIP:2376"],
    "tls": true,
    "tlscacert": "/root/certs/ca.pem",
    "tlscert": "/root/certs/server-cert.pem",
    "tlskey": "/root/certs/server-key.pem",
    "tlsverify": true

Also create a file in /etc/systemd/system/docker.service.d/docker.conf.


Reload your daemon settings systemctl daemon-reload and restart your Docker daemon with sudo service docker restart.

Add the Endpoint in Portainer

On the Portainer Web UI you now need to import the Certs and setup the connection.

Portainer Endpoint add Docker API

And then you should see that Portainer now has another endpoint successfully connected. And we now can manage our remote server from our main portainer instance, just like the local server.

Leave a Comment

I accept the Privacy Policy