This is how to connect to another host with your docker client, without modifying your local Docker installation or when you don't have a local Docker installation.
First be sure to enable the Docker Remote API on the remote host.
This can easily be done with a container.
For HTTP connection use jarkt/docker-remote-api.
For HTTPS connection use kekru/docker-remote-api-tls.
You can also configure the Docker engine to expose the remote API. Read Enable Docker Remote API with TLS client verification for more information.
If you don't have a local Docker installation, you need to download the docker client (= docker cli), which is a simple executable.
And then add it to your PATH variable.
Here are some ways how to get the executable.
You only need one of the steps for you OS, not all:
- Linux:
- Either: (Any Linux)
Download tgz file from download.docker.com/linux/static and unzip it. You only need thedockerfile, which must be added to your PATH.
Maybe this script helps downloading it.
Or just run:curl https://download.docker.com/linux/static/stable/x86_64/docker-19.03.8.tgz | tar xvz --directory /tmp && mv -v /tmp/docker/docker /usr/local/bin/docker && chmod +x /usr/local/bin/docker && rm -rf /tmp/docker
- Or: (Ubuntu/Debian)
From Install using the repository, but I would not recommend it, because there are many steps and much to install in the first steps
$ apt-get update $ apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add - # Verify correct gpg key $ apt-key fingerprint 0EBFCD88 $ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" $ apt-get update && apt-get install docker-ce-cli
- Or: (Centos)
$ yum install -y yum-utils $ yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo $ yum install -y docker-ce-cli
- Either: (Any Linux)
- MacOS:
- Either:
Download tgz file from download.docker.com/mac/static and unzip it. You only need thedockerfile, which must be added to your PATH. - Or:
Install Docker Desktop for Mac (Full Docker Engine in VM + client)
- Either:
- Windows
- Either: (Only old 2017 builds are available)
Download tgz file from download.docker.com/win/static and unzip it. You only need thedocker.exefile, which must be added to your PATH. - Or:
Download a build of StefanScherer/docker-cli-builder - Or: (Powershell with Chocolatey required)
$ choco install docker-cli
Will install latest StefanScherer/docker-cli-builder release for you. - Or: (Windows 10 Pro required)
Install Docker Desktop for Windows (Full Docker Engine in VM + client)
- Either: (Only old 2017 builds are available)
See also the official installation site and Install Docker Engine from binaries
Docker's Remote API client authentication works with certificates.
See Protect the Docker daemon socket or my Enable Docker Remote API with TLS client verification on how to create server and client certificates.
For the following examples copy ca.pem (CA certificate), cert.pem (client certificate) and key.pem (client's private key) in /home/me/docker-tls/ or C:\users\me\docker-tls\.
Now we will see some ways on how to connect to a docker remote api.
For HTTP connection set the following alias:
alias dockerx="docker -H=your-remote-server.org:2375"For HTTPS connection set the following alias:
alias dockerx="docker \
--tlsverify \
-H=your-remote-server.org:2376 \
--tlscacert=/home/me/docker-tls/ca.pem \
--tlscert=/home/me/docker-tls/cert.pem \
--tlskey=/home/me/docker-tls/key.pem"Now you can run commands on the remote machine with dockerx instead of docker.
Example:
dockerx psCreate a file dockerx.bat.
For HTTP connection the content of the bat file should be:
docker -H=your-remote-server.org:2375 %*For HTTPS connection the content of the bat file should be:
docker ^
--tlsverify ^
-H=your-remote-server.org:2376 ^
--tlscacert=C:\users\me\docker-tls\ca.pem ^
--tlscert=C:\users\me\docker-tls\cert.pem ^
--tlskey=C:\users\me\docker-tls\key.pem %*(If this does not work remove the carets (^) and the line breaks)
Now you can run commands on the remote machine with dockerx.bat instead of docker.
Example:
dockerx.bat psYou can set environment vars to define the docker remote api that should be connected to.
For HTTP connection
# Linux/Mac
export DOCKER_HOST="tcp://your-remote-server.org:2375"
# Windows Powershell
$env:DOCKER_HOST="tcp://your-remote-server.org:2375"For HTTPS connection
# Linux/Mac
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://your-remote-server.org:2376"
export DOCKER_CERT_PATH="/home/me/docker-tls"
# Windows Powershell
$env:DOCKER_TLS_VERIFY="1"
$env:DOCKER_HOST="tcp://your-remote-server.org:2376"
$env:DOCKER_CERT_PATH="C:\users\me\docker-tls"Be sure that your DOCKER_CERT_PATH directory contains the following files:
- ca.pem (CA certificate)
- cert.pem (client certificate)
- key.pem (client's private key)
Now any docker command will run against the remote api
docker psDo switch back to local docker, unset the env vars:
# Linux/Mac
unset DOCKER_HOST
unset DOCKER_TLS_VERIFY
unset DOCKER_CERT_PATH
# Windows Powershell
Remove-Item env:DOCKER_HOST
Remove-Item env:DOCKER_TLS_VERIFY
Remove-Item env:DOCKER_CERT_PATHIf you already added an SSH public key to your remote server, then you can use this ssh credentials for your docker connection, too. You don't need to configure the remote api on the server for this approach.
(Should work on Windows, but I did only test on Linux yet)
Set the env var to a ssh address:
# Linux/Mac
export DOCKER_HOST="ssh://[email protected]"
# Windows Powershell
$env:DOCKER_HOST="ssh://[email protected]"Now any docker command will run against the remote api
docker psDo switch back to local docker, unset the env vars:
# Linux/Mac
unset DOCKER_HOST
# Windows Powershell
Remove-Item env:DOCKER_HOSTSince Docker 19.03 there is the docker context command. You can define multiple remote servers and switch between them.
Create a context for HTTPS
(Change paths for Windows)
docker context create example-server \
--description "connection to example server" \
--docker "host=tcp://your-remote-server.org:2376, \
ca=/home/me/docker-tls/ca.pem, \
cert=/home/me/docker-tls/cert.pem, \
key=/home/me/docker-tls/key.pem"(For HTTP connection remove ca, cert and key and switch port to 2375. For SSH connection use ssh address)
Now you can call the remote server with:
docker --context example-server psOr choose the context and then all following command will call the remote server
docker context use example-server
docker ps
It would be nice if the SSH-approache is verified for windows.
Since Docker updated ther subscription this would be an accepteable drop-in-replacement for Docker-Desktop on Windows.
Sure, you will need some configuration for WSL2 and Docker-cli, but this would be better then pay for featueres you don't need.