goharbor / goharbor/website

Suggested Documentation Improvements

Open
#666 5 comments 0 reactions 0 assignees View on GitHub
help wanted
Dominant language
HTML
Stars
46
Forks
222
PR merge metrics
No merged PRs in 30d

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_](https://goharbor.io/docs/2.13.0/install-config/) 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

1. That the `https->certificate` field for a Let's Encrypt certificate should be the full chain: `/etc/letsencrypt/live//fullchain.pem`,
2. What if anything is required in terms of prerequisites to turn on `strong_ssl_ciphers`, and
3. The username for the admin login. It's `admin` not `harbor_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_](https://goharbor.io/docs/2.13.0/working-with-projects/working-with-images/) Page:

1. The _Preheat Images_ Page could better describe what "P2P Preheat" is, and when it's useful. Not used for private repos?
2. The _Pulling and Pushing Images in the Docker Client_ Page doesn't make clear that `` means `[:]`
3. And the _Pushing Images_ Section of this page doesn't make clear that for the example
```
docker push /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](/basecamp/kamal) I use, the target image name, which needed to be set to `/` for 3rd-party registries, now needed to become `` = `/`. When I instead set this to ``, 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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.