How to Install and Configure Harbor

Harbor is an open-source container image registry that secures images with role-based access control, scans images for vulnerabilities, and signs images as trusted. It serves as a central repository for container images, ensuring their integrity and access control across environments. In this guide, you’ll learn how to install the latest version of Harbor and configure it for storing container images.

Harbor can be deployed as a set of Docker containers, and this tutorial assumes you have Docker and Docker Compose installed.

Prerequisites

Before you begin, ensure you have the following prerequisites:

Operating System: A server running a supported Linux distribution (e.g., Ubuntu 20.04 or CentOS 7).
Root or Sudo Access: Administrative privileges to install software and modify system configurations.
Docker: Docker Engine version 17.06.0-ce or later installed.
Docker Compose: Docker Compose version 1.18.0 or later installed.
Domain Name: A fully qualified domain name (FQDN) for accessing Harbor.

Ensure all these prerequisites are met before proceeding with the installation and configuration of Harbor.

Step 1: Download and Extract the Harbor Installer

To install Harbor, the first step is downloading and extracting the Harbor installer. Follow these instructions:

Download the Latest Installer

Use the following command to download the offline installer for the latest version of Harbor (v2.12.1 in this example):

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

Extract the Installer

Extract the downloaded installer:

   tar xzvf harbor-offline-installer-v2.12.1.tgz

The extraction creates a directory named harbor with the following files:

   harbor/harbor.v2.12.1.tar.gz
   harbor/prepare
   harbor/LICENSE
   harbor/install.sh
   harbor/common.sh
   harbor/harbor.yml.tmpl

Verify the Installer Directory

Navigate to the harbor directory:

   cd harbor

Verify its contents by listing the files:

ls

The output should be:

   harbor.v2.12.1.tar.gz
   prepare
   LICENSE
   install.sh
   common.sh
   harbor.yml.tmpl

You’re now ready to move to Step 2, where you’ll configure the harbor.yml file to prepare for Harbor installation.

Step 2: Configure the `harbor.yml` File

Before installing Harbor, you must configure the harbor.yml file to define the system settings and parameters. Follow these steps to set up the configuration:

Locate the `harbor.yml` Template

The extracted Harbor installer includes a configuration template file named harbor.yml.tmpl. You need to create the harbor.yml file based on this template.

Navigate to the Harbor directory:

   cd harbor

Copy the template file to create the actual configuration file:

   cp harbor.yml.tmpl harbor.yml

Edit the `harbor.yml` File

Open the harbor.yml file in a text editor (e.g., nano or vim):

   nano harbor.yml

Modify the following key parameters:

hostname: Set this to the IP address or fully qualified domain name (FQDN) of your Harbor server. hostname: <example.com> Replace <example.com> with your server’s actual domain or hostname.
HTTPS Configuration: Enable HTTPS by specifying the certificate and private key paths. https: port: 443 certificate: /etc/letsencrypt/live/<example.com>/fullchain.pem private_key: /etc/letsencrypt/live/<example.com>/privkey.pem Replace <example.com> with your domain.
Admin Password: Set an initial password for the Harbor admin user. The default username is admin. harbor_admin_password: YourStrongPassword
Data Volume: Specify the directory where Harbor will store data. The default is /data. data_volume: /data
Database Password: Optionally, set a password for the internal PostgreSQL database.
yaml database: password: YourDatabasePassword

Save and close the file.

Generate SSL Certificates with Certbot

If you do not already have an SSL certificate for your domain, you can generate one using Certbot and Let’s Encrypt.

Install Certbot on your system:

For Ubuntu/Debian:
bash sudo apt update sudo apt install certbot -y
For CentOS/RHEL:
bash sudo yum install certbot -y

Stop any services using ports 80 and 443, such as Nginx or Apache:

   sudo systemctl stop nginx
   sudo systemctl stop apache2

Run Certbot to generate the certificate:

   sudo certbot certonly --standalone --agree-tos --no-eff-email --email [email protected] -d <example.com>

This will create the certificate and private key in the /etc/letsencrypt/live/<example.com>/ directory.

Restart any stopped services:

   sudo systemctl start nginx

Verify the Configuration

Check that the harbor.yml file has been updated correctly:

cat harbor.yml

Ensure all parameters reflect your intended configuration.

With the harbor.yml file configured, including the SSL certificate paths, you are now ready to proceed to Step 3, where you’ll install and start Harbor.

Step 3: Install Docker, and Start Harbor Installation

Harbor requires Docker (version 17.06.0-ce or later) and Docker Compose (version 1.18.0 or later). Follow these steps to ensure Docker and Docker Compose are installed correctly before proceeding with Harbor installation.

Remove Old Docker Versions

If you have older versions of Docker or related packages installed, remove them to avoid conflicts:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

Set Up Docker’s apt Repository

Before installing Docker, add its official repository to your system:

Update the package index and install required dependencies:

   sudo apt-get update
   sudo apt-get install ca-certificates curl

Add Docker’s GPG key:

   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the Docker repository to apt sources:

   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update

Note: For Ubuntu derivatives (e.g., Linux Mint), use UBUNTU_CODENAME instead of VERSION_CODENAME.

Install Docker

Install the latest version of Docker:

   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify the Docker installation:

   sudo docker run hello-world

This command downloads a test image and runs it in a container, printing a confirmation message.

Install Docker Compose

Update the package index:

   sudo apt-get update

Install the Docker Compose plugin:

   sudo apt-get install docker-compose-plugin

Verify Docker Compose installation:

   docker compose version

You should see output similar to:

   Docker Compose version vN.N.N

Run the Harbor Installation Script

Navigate to the Harbor directory:

   cd harbor

Run the installation script:

   sudo ./install.sh

Start Harbor Services

Use Docker Compose to start Harbor:

   docker compose up -d

This command starts Harbor services as containers in detached mode. The output should resemble:

   [+] Running 9/0
   ✔ Container harbor-log         Running                                                                                                                 0.0s
   ✔ Container registryctl        Running                                                                                                                 0.0s
   ✔ Container harbor-portal      Running                                                                                                                 0.0s
   ✔ Container redis              Running                                                                                                                 0.0s
   ✔ Container harbor-db          Running                                                                                                                 0.0s
   ✔ Container registry           Running                                                                                                                 0.0s
   ✔ Container harbor-core        Running                                                                                                                 0.0s
   ✔ Container nginx              Running                                                                                                                 0.0s
   ✔ Container harbor-jobservice  Running                                                                                                                 0.0s

Verify that the containers are running:

   sudo docker ps

You should see several containers, including nginx, core, portal, and others, in a running state.

Access the Harbor Interface

Open a web browser and navigate to your Harbor instance:

   https://<example.com>

Harbor is now successfully installed and ready for use. Proceed to configure image storage and push/pull operations in the next step.

Step 4: Configure Image Storage and Push/Pull Operations

Once Harbor is successfully installed and running, you can start configuring image storage and perform push/pull operations. Follow the steps below:

Create a Project in Harbor

URL: https://<example.com>
Username: admin
Password: The one you set in harbor.yml.

Navigate to the Projects tab.
Click New Project, and provide the following details:

Project Name: my-project (or any desired name).
Access Level: Choose Private to restrict access or Public for open access.

Save the project.

Log In to Harbor from Docker

Before pushing or pulling images, you need to authenticate your Docker client with Harbor.

Use the following command to log in:

   docker login <example.com>

Enter your Harbor username (admin) and password when prompted.

Push an Image to Harbor

Tag the image you want to push, associating it with your Harbor repository:

   docker tag ubuntu:latest <example.com>/my-project/ubuntu:latest

Push the tagged image:

   docker push <example.com>/my-project/ubuntu:latest

Verify the image in the Harbor web interface under Projects > my-project.

Pull an Image from Harbor

To pull the image back from Harbor to a Docker client:

Use the following command:

   docker pull <example.com>/my-project/ubuntu:latest

Confirm the image is pulled by listing local images:

   docker images

Optional: Enable Content Trust (Notary)

If you wish to enable image signing for additional security:

Configure Docker to use content trust:

   export DOCKER_CONTENT_TRUST=1

Push or pull images as usual to ensure they are signed.

Harbor is now configured for storing and managing container images. You can use these steps to efficiently manage your Docker images within Harbor.

Introduction