Suggested Documentation Improvements #666
Description
Today I installed Harbor and used it to deploy a website, switching from the Docker Hub registry. I was amazed that this was a fairly quick and painless process. Congratulations. Several times however I was stumped on how to proceed. Here are the things I think could be clearer in the documentation:
I followed the Harbor Installation and Configuration page.
I was first stuck at Step 3: Configure HTTPS Access to Harbor. It should have been made clearer that this very long process could be skipped if you have a TLS cert for the domain on which you are to host Harbor, issued by a 3rd-party (e.g. Let’s Encrypt), setting it directly in the harbor.yml file. This should be stated in Point 3 itself.
Not realising this, I was reading the Configure HTTPS Access to Harbor text, becoming stumped when it said to copy the certs to the /data/cert/ directory. I couldn't find this directory in either the online or offline installers.
It should also be made clear in Point 2 (Download the Harbor Installer) that the installer can be untarred anywhere by any user in the docker group. It will create its own installation subdirectory that is only used for the installation process: it is not used for a set of Harbor files that need to be kept around, nor does the installation process create another directory that needs to be kept around. It all goes in to the containers.
What I found unclear in Point 4, Configure the Harbor YML File, was
- That the
https->certificatefield for a Let's Encrypt certificate should be the full chain:/etc/letsencrypt/live/<hostname>/fullchain.pem, - What if anything is required in terms of prerequisites to turn on
strong_ssl_ciphers, and - The username for the admin login. It's
adminnotharbor_admin.
After that, I was amazed that install.sh worked to completion, and I could access the admin website (even via a non-standard port so as not to interfere with normal web-serving).
On the web UI, once I worked out the admin username, I was first confused that I couldn't reset the admin password. I had to create a new admin user, after which the admin user disappeared.
My final difficulties came on the Working with Images and Tags Page:
- The Preheat Images Page could better describe what "P2P Preheat" is, and when it's useful. Not used for private repos?
- The Pulling and Pushing Images in the Docker Client Page doesn't make clear that
<harbor_address>means<hostname>[:<port>] - And the Pushing Images Section of this page doesn't make clear that for the example
docker push <harbor_address>/demo/ubuntu:14.04
demo is the project name, demo/ubuntu becomes the repository name, and 14.04 becomes the tag.
This meant that in the Kamal deployer I use, the target image name, which needed to be set to <registry-username>/<repository-name> for 3rd-party registries, now needed to become <repository-name> = <project-name>/<image-name>. When I instead set this to <project-name>, I was stumped with docker push unexpected status from HEAD request errors. For many people the project and image names will be the same, so an image field of the form xxx/xxx wasn't obvious.
Anyway, I hope this view from an inexperienced user was helpful. Overall I was impressed by how easy it was to change to self-hosting.