whiledo/docker-remote-api-tls repository overview

⁠Docker Remote API with TLS client authentication via container

This images makes you publish your Docker Remote API by a container. A client must authenticate with a client-TLS certificate. This is an alternative way, instead of configuring TLS on Docker directly⁠.

⁠Remote Api with external CA, certificates and key

First you need a CA and certs and keys for your Docker server and the client.

Create them as shown here Protect the Docker daemon socket⁠. Or create the files with this script create-certs.sh⁠. Read Create certificate files⁠ for information on how to use the script.

Copy the following files in a directory. The directory will me mounted in the container.

ca-cert.pem
server-cert.pem
server-key.pem

The files cert.pem and key.pem are certificate and key for the client. The client will also need the ca-cert.pem.

Create a docker-compose.yml file:

version: "3.4"
services:
  remote-api:
    image: kekru/docker-remote-api-tls:v0.3.0
    ports:
     - 2376:443
    volumes:
     - <local cert dir>:/data/certs:ro
     - /var/run/docker.sock:/var/run/docker.sock:ro

Now run the container with docker-compose up -d or docker stack deploy --compose-file=docker-compose.yml remoteapi. Your Docker Remote API is available on port 2376 via https. The client needs to authenticate via cert.pem and key.pem.

⁠Remote Api with auto generating CA, certificates and keys

The docker-remote-api image can generate CA, certificates and keys for you automatically. Create a docker-compose.yml file, specifying a password and the hostname, on which the remote api will be accessible later on. The hostname will be written to the server's certificate.

version: "3.4"
services:
  remote-api:
    image: kekru/docker-remote-api-tls:v0.3.0
    ports:
     - 2376:443
    environment:
     - CREATE_CERTS_WITH_PW=supersecret
     - CERT_HOSTNAME=remote-api.example.com
    volumes:
     - <local cert dir>:/data/certs
     - /var/run/docker.sock:/var/run/docker.sock:ro

Now run the container with docker-compose up -d or docker stack deploy --compose-file=docker-compose.yml remoteapi. Certificates will be created in <local cert dir>. You will find the client-certs in <local cert dir>/client/. The files are ca.pem, cert.pem and key.pem.

⁠Environment variables

⁠CREATE_CERTS_WITH_PW

Passphrase to encrypt the certificate.

⁠CERTS_PASSWORD_FILE

Certificate passphrase will be read from this docker secret. Absolute path of the secret file has to be provided i.e. CERTS_PASSWORD_FILE=/run/secrets/<secret_name>.

If both passphrase and secret file are set, the secret file takes precedence.

⁠CERT_EXPIRATION_DAYS

Certificate expiration for server and client certs in days. If not set, the default value 365 is applied.

⁠CA_EXPIRATION_DAYS

Certificate expiration for CA in days. If not set, the default value 900 is applied.

⁠CERT_HOSTNAME

Domain name of the docker server.
If you don't have a DNS name, you can use nip.io⁠ to get a name for any IP.

⁠Setup client

See Run commands on remote Docker host⁠ for instructions how to setup a client to communicate with the remote api.

You can also reuse dockerRemote⁠ and set url and path in it to your correct values.
Then just run ./dockerRemote ps to call ps against your remote api.

⁠Quick test

To test this repo quickly, clone this repo, then run

# Start remote-api locally
docker-compose up -d
# Run ps over remote api (use GitBash when you are on Windows)
./dockerRemote ps

⁠Changelog

⁠v0.2.0

First stable release
Thanks @smiller171⁠ for contributing!

⁠v0.3.0

• update nginx version
• add configuration for cert expiration
• add configuration to use swarm secret as password for cert generation
• add automatic tests

Thanks @benkorichard⁠ for contributing!