diff --git a/docs/credential-helpers.md b/docs/credential-helpers.md deleted file mode 100644 index c86ef7c..0000000 --- a/docs/credential-helpers.md +++ /dev/null @@ -1,66 +0,0 @@ -Some private docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication. -To be able to use this together with watchtower, we need to use a credential helper. - -To keep the image size small we've decided to not include any helpers in the watchtower image, instead we'll put the -helper in a separate container and mount it using volumes. - -### Example -Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper): - -```Dockerfile -FROM golang:latest - -ENV CGO_ENABLED 0 -ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login - -RUN go get -u $REPO - -RUN rm /go/bin/docker-credential-ecr-login - -RUN go build \ - -o /go/bin/docker-credential-ecr-login \ - /go/src/$REPO - -WORKDIR /go/bin/ -``` - -and the docker-compose definition: -```yaml -version: "3" - -services: - watchtower: - image: index.docker.io/containrrr/watchtower:latest - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - /.docker/config.json:/config.json - - helper:/go/bin - environment: - - HOME=/ - - PATH=$PATH:/go/bin - - AWS_REGION= - - AWS_ACCESS_KEY_ID= - - AWS_SECRET_ACCESS_KEY= -volumes: - helper: {} -``` - -and for `/.docker/config.json`: -```json - { - "HttpHeaders" : { - "User-Agent" : "Docker-Client/19.03.1 (XXXXXX)" - }, - "credsStore" : "osxkeychain", - "auths" : { - "xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : {}, - "https://index.docker.io/v1/": {} - }, - "credHelpers": { - "xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : "ecr-login", - "index.docker.io": "osxkeychain" - } - } -``` - -*Note:* `osxkeychain` can be changed to your prefered credentials helper. diff --git a/docs/private-registries.md b/docs/private-registries.md new file mode 100644 index 0000000..13e7618 --- /dev/null +++ b/docs/private-registries.md @@ -0,0 +1,118 @@ +Watchtower supports private Docker image registries. In many cases, accessing a private registry requires a valid username and password (i.e., _credentials_). In order to operate in such an environment, watchtower needs to know the credentials to access the registry. + +The credentials can be provided to watchtower in a configuration file called `config.json`. There are two ways to generate this configuration file: + +* The configuration file can be created manually. +* Call `docker login ` and share the resulting configuration file. + +### Create the configuration file manually +Create a new configuration file with the following syntax and a base64 encoded username and password `auth` string: +```json +{ + "auths": { + "": { + "auth": "XXXXXXX" + } + } +} +``` + +`` needs to be replaced by the name of your private registry (e.g., `my-private-registry.example.org`) + +The required `auth` string can be generated as follows: +```bash +echo -n 'username:password' | base64 +``` + +When the watchtower Docker container is started, the created configuration file (`/config.json` in this example) needs to be passed to the container: +```bash +docker run [...] -v /config.json:/config.json containrrr/watchtower +``` + +### Share the Docker configuration file +To pull an image from a private registry, `docker login` needs to be called first, to get access to the registry. The provided credentials are stored in a configuration file called `/.docker/config.json`. This configuration file can be directly used by watchtower. In this case, the creation of an additional configuration file is not necessary. + +When the Docker container is started, pass the configuration file to watchtower: +```bash +docker run [...] -v /.docker/config.json:/config.json containrrr/watchtower +``` + +When creating the watchtower container via docker-compose, use the following lines: +```yaml +version: "3" +[...] +watchtower: + image: index.docker.io/containrrr/watchtower:latest + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - /.docker/config.json:/config.json +[...] +``` + +## Credential helpers +Some private Docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication. +To be able to use this together with watchtower, we need to use a credential helper. + +To keep the image size small we've decided to not include any helpers in the watchtower image, instead we'll put the +helper in a separate container and mount it using volumes. + +### Example +Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper): + +```Dockerfile +FROM golang:latest + +ENV CGO_ENABLED 0 +ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login + +RUN go get -u $REPO + +RUN rm /go/bin/docker-credential-ecr-login + +RUN go build \ + -o /go/bin/docker-credential-ecr-login \ + /go/src/$REPO + +WORKDIR /go/bin/ +``` + +and the docker-compose definition: +```yaml +version: "3" + +services: + watchtower: + image: index.docker.io/containrrr/watchtower:latest + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - /.docker/config.json:/config.json + - helper:/go/bin + environment: + - HOME=/ + - PATH=$PATH:/go/bin + - AWS_REGION= + - AWS_ACCESS_KEY_ID= + - AWS_SECRET_ACCESS_KEY= +volumes: + helper: {} +``` + +and for `/.docker/config.json`: +```json + { + "HttpHeaders" : { + "User-Agent" : "Docker-Client/19.03.1 (XXXXXX)" + }, + "credsStore" : "osxkeychain", + "auths" : { + "xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : {}, + "https://index.docker.io/v1/": {} + }, + "credHelpers": { + "xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com" : "ecr-login", + "index.docker.io": "osxkeychain" + } + } +``` + +*Note:* `osxkeychain` can be changed to your prefered credentials helper. diff --git a/mkdocs.yml b/mkdocs.yml index e5e7c34..645c1cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,7 +14,7 @@ nav: - 'Arguments': 'arguments.md' - 'Notifications': 'notifications.md' - 'Container selection': 'container-selection.md' - - 'Credential helpers': 'credential-helpers.md' + - 'Private registries': 'private-registries.md' - 'Linked containers': 'linked-containers.md' - 'Remote hosts': 'remote-hosts.md' - 'Secure connections': 'secure-connections.md'