Install Harbor¶

The official installation doc can be found here

1. Prepare prerequisites¶

You can find the complete requirement here

Hardware¶

The following table lists the minimum and recommended hardware configurations for deploying Harbor.

Resource    Minimum Recommended
CPU 2 CPU   4 CPU
Mem 4 GB    8 GB
Disk    40 GB   160 GB

Software¶

The following table lists the software versions that must be installed on the target host.

docker engine
docker compose
openssl

To install docker engine and compose, you can follow this doc.

# install openssl
sudo apt install openssl

2. Download the harbor Installer¶

The official release page is here. You can find two type of installer: - Online: The online installer downloads the Harbor images from Docker hub. For this reason, the installer is very small in size. - Offline: The offline installer contains pre-built images, so it is larger than the online installer. Use the offline installer if the host to which are deploying Harbor does not have a connection to the Internet.

In this tutorial, we use the offline installer of harbor v2.6.1 (latest of 02/11/2022)

# download the installer 
wget https://github.com/goharbor/harbor/releases/download/v2.6.1/harbor-offline-installer-v2.6.1.tgz

# unzip it
tar -xzvf harbor-offline-installer-version.tgz

# after unzip, you should see a folder harbor with below content
harbor
├── common.sh
├── harbor.v2.6.1.tar.gz
├── harbor.yml.tmpl
├── install.sh
├── LICENSE
└── prepare

harbor.yml.tmpl: is the config template
prepare : is the preconfig script for setup https and required certficate

3. Prepare certificate¶

If you don't have CA and client certs, you can follow the PKI_cfssl doc to generate them.

If you already have them, you can put them in - certificate folder of your harbor host: /data/cert/. In the harbor.yml, we will mount /data to the harbor container. - docker certificate folder /etc/docker/certs.d/yourdomain.com/. In our case, it should be /etc/docker/certs.d/casd.local

The Docker daemon interprets .crt files as CA certificates and .cert files as client certificates. So you may need to convert your client certificate from .crt to .cert format

# convert client certificate format
# in fact, the content is the same for the two format, so you can just rename it with .cert.
openssl x509 -inform PEM -in casd.local.crt -out casd.local.cert

# copy them into harbor cert folder
cp casd.local.crt /data/cert/
cp casd.local.key /data/cert/

# copy them into the docker cert folder
cp casd.local.cert /etc/docker/certs.d/casd.local/
cp casd.local.key /etc/docker/certs.d/casd.local/
cp ca.crt /etc/docker/certs.d/casd.local/

Custom port¶

If you mapped the default nginx port 443 to a different port, create the folder with the custom port

# with a domain name
/etc/docker/certs.d/yourdomain.com:port

# or with an ip if you want to expose harbor with an IP
/etc/docker/certs.d/harbor_IP:port.

You need to restart docker systemctl restart docker to make change effective.

4. Configure Harbor Yaml file¶

# use the template as the base of the config
cp harbor.yml.tmpl harbor.yml.

You can find a complete explication about every attribute on this page.

We recommend you to at least change the

hostname
https with appropriate certificates
admin password
data_volume

You can find an example in harbor.yaml

5. Run the installer script¶

Once you have configured harbor.yml, you can install and run Harbor by using install.sh script.

By default, it only deploys Harbor, you can enable other modules with extra options - Notary : The module which can verify the origin of an image. More doc here

Trivy : Vulnerabilites scanner of image. More doc here
chartmuseum: an open source helm chart repository server. More doc here

Notary and chartmuseum is deprecated since Harbor v2.7.0.

# Without any extra module
sudo ./install.sh

# with all module
sudo ./install.sh --with-trivy

This command will first generate all required manifest and config for docker compose in /path/to/harbor/common/config, then apply them with docker compose.

--with-notary --with-chartmuseum option are deprecated, don't use them.

Some bug¶

There is some kind of bug with the current release that I'm unable to identify. Sometime when you start the harbor service, you can see the tool bar of a project and you can't use docker login to connet with harbor.

To overcome this bug, you need to restart it

# Restart Docker Engine.

sudo systemctl restart docker

# Stop Harbor. This command must run under the /path/to/harbor
docker compose down -v

# start harbor. This command must run under the /path/to/harbor
docker compose up -d

You can find the official doc on harbor reconfigure here

6. Working with harbor¶

https://goharbor.io/docs/1.10/working-with-projects/

6.1 Create a project in Harbor¶

There are two types of project in Harbor:

Public: Any user can pull images from this project. This is a convenient way for you to share repositories with others.
Private: Only users who are members of the project can pull images
Go to Projects and click New Project.
Provide a name for the project.
(Optional) Check the Public check box to make the project public.

For more detail, please visit this page

6.2 Config a project¶

Web User Interface

6.3 Push a docker image to the created project¶

Note if you want to push an image to harbor, you must tag the image in the local repo with below general form is <harbor-host-name>/<project-name>/<repo-name>:<tag>. tag is optional, if ommited, latest version will be used.

For example, below is a minimum docker file. You can find the full example in sample_docker_file

FROM busybox:latest
LABEL MAINTAINER=pengfei.liu@casd.eu
LABEL version="1.0"
COPY config.sh /etc/spark/config.sh
RUN cat /etc/spark/config.sh

# login to harbor registry
docker login <harbor-url>

# Build an image from this Dockerfile and tag it.

docker build -t reg.casd.local/test/test-image .

# Push the image from local repo to remote repo
docker push reg.casd.local/test/test-image

If you pull the image from other registry, you need to re-tag it to push to harbor. Below example shows how to pull image from dockerhub, then push the image to harbor

# pull image from dockerhub
docker pull liupengfei99/mlflow

# retag the image, the first argument is the source, second is the destination
docker tag liupengfei99/mlflow reg.casd.local/test/mlflow

For more example on how to push local image to remote repository, you can visit this page

After this step, you should see a new repository test-image created in project test

6.4 Pull a docker image from harbor¶

To pull an image from harbor via docker client, please follow below command

# login to harbor registry
docker login <harbor-url>

# pull the image from remote repo to local repo
docker pull reg.casd.local/test/test-image

6.5 Managing labels¶

Global level label¶

The Harbor system administrators can list, create, update and delete the global level labels under Administration->Configuration->Labels

Project level label¶

The project administrators and Harbor system administrators can list, create, update and delete the project level labels under Labels tab.

Adding and Removing Labels to and from Images¶

Users who have Harbor system administrator, project administrator or project developer role can click the ADD LABELS button to add labels to or remove labels from images. The label list contains both globel level labels(come first) and project level labels.

6.6 Tag and re-tag image¶

Harbor allows an image to have multiple tags. Open an image and click on add a tag button to add a new tag.

Retag (copy to another project with new tag)¶

Harbor allows you to re-tag an image.

For more information, please visit this page