Update the README of your container repo on Dockerhub, Quay or Harbor with a simple Docker command:
$ ls
README.md
$ docker pushrm my-user/hello-world
docker-pushrm
is a Docker CLI plugin that adds a new docker pushrm
(speak: "push readme") command to Docker.
It pushes the README file from the current working directory to a container registry server where it appears as repo description in the webinterface.
It currently supports Dockerhub (cloud), Red Hat Quay (cloud and self-hosted/OpenShift) and Harbor v2 (self-hosted).
For most registry types docker-pushrm
uses authentication info from the Docker credentials store - so it "just works" for registry servers that you're already logged into with Docker.
(For some other registry types, you'll need to pass an API key via env var or config file).
Let's build a container image, push it to Dockerhub and then also push the README to Dockerhub:
$ ls
Dockerfile README.md
$ docker login
Username: my-user
Password: ********
Login Succeeded
$ docker build -t my-user/hello-world .
$ docker push my-user/hello-world
$ docker pushrm my-user/hello-world
When we now browse to the repo in the Dockerhub webinterface we should find the repo's README to be updated with the contents of the local README file.
The same works for Harbor version 2 registry servers:
docker pushrm --provider harbor2 demo.goharbor.io/myproject/hello-world
And also for Quay/OpenShift cloud and self-hosted registry servers:
docker pushrm --provider quay quay.io/my-user/hello-world
For Dockerhub it's also possible to set the repo's short description with -s "some description"
.
In case that you want different content to appear in the README on the container registry than on the git repo (for github/gitlab), you can create a dedicated README-containers.md
, which takes precedence. It's also possible to specify a path to a README file with --file <path>
.
- make sure Docker or Docker Desktop is installed
- Download
docker-pushrm
for your platform from the release page. - copy it to:
- Windows:
c:\Users\<your-username>\.docker\cli-plugins\docker-pushrm.exe
- Mac + Linux:
$HOME/.docker/cli-plugins/docker-pushrm
- Windows:
- on Mac/Linux make it executable:
chmod +x $HOME/.docker/cli-plugins/docker-pushrm
Now you should be able to run docker pushrm --help
.
There's also a Docker/OCI container image of this tool. See separate docs for how to use it. This is mainly intended for use in CI workflows.
This tool is also available as a github action here.
docker login
docker login <servername>
Example:
docker login demo.goharbor.io
If you want to be able to push containers, you need to log in as usual:
- for Quay cloud:
docker login quay.io
- for self-hosted Quay server or OpenShift:
docker login <servername>
(example:docker login my-server.com
)
In addition to be able to use docker-pushrm
you need to set up an API key:
First, log into the Quay webinterface and create an API key:
- if you don't have an organization create a new organization (your repos don't need to be under the organization's namespace, this is just to unlock the "apps" settings page)
- navigate to the org and open the
applications
tab create new app
and give it some name- click on the app name and open to the
generate token
tab - create a token with permissions
Read/Write to any accessible repositories
- after confirming you should now see the token secret. Write it down in a safe place.
(Refer to the Quay docs for more info)
Then, make the API key available to docker-pushrm
. There are two options for that: Either set an environment variable (recommended for CI) or add it to the Docker config file (recommended for Desktop use). (If both are present, the env var takes precedence).
set an environment variable DOCKER_APIKEY=<apikey>
or APIKEY__<SERVERNAME>_<DOMAIN>=<apikey>
example for servername quay.io
:
export APIKEY__QUAY_IO=my-api-key
docker pushrm quay.io/my-user/my-repo
In the Docker config file (default: $HOME/.docker/config.json
) add a json key plugins.docker-pushrm.apikey_<servername>
with the api key as string value.
Example for servername quay.io
:
{
...,
"plugins" : {
"docker-pushrm" : {
"apikey_quay.io" : "my-api-key"
}
},
...
}
Alternatively credentials can be set as environment variables. Environment variables take precedence over the Docker credentials store. Environment variables can be specified with or without a server name. The variant without a server name takes precedence.
This is intended for running docker-pushrm
as a standalone tool in a CI environment (no full Docker installation needed).
DOCKER_USER
andDOCKER_PASS
DOCKER_USER__<SERVER>_<DOMAIN>
andDOCKER_PASS__<SERVER>_<DOMAIN>
(example for serverdocker.io
:DOCKER_USER__DOCKER_IO=my-user
andDOCKER_PASS__DOCKER_IO=my-password
)
The provider 'quay' needs an additional env var for the API key in form of APIKEY__<SERVERNAME>_<DOMAIN>=<apikey>
.
Example:
DOCKER_USER=my-user DOCKER_PASS=mypass docker-pushrm my-user/my-repo
You can still use docker-pushrm
as standalone executable.
The only obstacle is that you need to provide it credentials in the Docker style.
The easiest way for that is to set up a minimal Docker config file with the registry server logins that you need. (Alternatively credentials can be passed in environment variables )
You can either create this config file on a computer with Docker installed (by running docker login
and then copying the $HOME/.docker/config.json
file).
Or alternatively you can also set it up manually. Here's an example:
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "xxx"
},
"https://demo.goharbor.io": {
"auth": "xxx"
}
},
}
The auth value is base64 of <user>:<passwd>
(i.e. myuser:mypasswd
)
It's also possible to use Docker credential helpers on systems that don't have Docker installed to avoid clear text passwords in the config file. The credential helper needs to be configured in the Docker config file and the credential helper executable needs to be in the PATH
. (Check the Docker docs for details).
Please open an issue.
To install the plugin for all users of a system copy it to the following path (instead of to the user home dir). Requires admin/root privs.
- Linux: depending on the distro, either
/usr/lib/docker/cli-plugins/docker-pushrm
or/usr/libexec/docker/cli-plugins/docker-pushrm
- Windows:
%ProgramData%\Docker\cli-plugins\docker-pushrm.exe
- Mac:
/Applications/Docker.app/Contents/Resources/cli-plugins/docker-pushrm
On Mac/Linux make it executable and readable for all users: chmod a+rx <path>/docker-pushrm
Pushing READMEs to Dockerhub currently only works with username/password and not with personal access tokens. If you have 2FA auth (two-factor authentication) enabled for your Dockerhub account you're effectively using a personal access token. This is an unfortunate Dockerhub API limitation.
There are indications (in issues and forum posts) that a new API for Dockerhub might be coming up sooner or later that might fill this gap. Fingers crossed. 🤞
All trademarks, logos and website designs belong to their respective owners.