How to install Harbor on Ubuntu Server 18.04

Harbor is a trusted on-premises docker registry that works with Content Trust. Find out how to get this up and running.


Jack Wallen

If you're looking to host your own Docker registry, one thing you need to consider is doing so with a certain level of trust. Some applications are capable of working with Docker content trust and some are not. With Content Trust you can sign your Docker images such that they can be trusted. But how? One way is by deploying Harbor. 

Harbor is an open source trusted cloud native registry project that stores, signs, and scans content to be stored in an on-premises registry.

SEE: Hybrid cloud: A guide for IT pros (TechRepublic download)

I'm going to walk you through the process of installing Harbor on Ubuntu Server 18.04. Successful installation isn't well-documented, but I've worked it out to make it easier for you.

What you'll need

The only things you'll need for a successful installation are:

  • A running instance of Ubuntu Server 18.04
  • A user account with sudo privileges
  • Patience

With that said, let's install.

Install dependencies

The first thing to take care of is installing docker and docker-compose. Docker can be installed from the standard repositories with the command:

sudo apt-get install

Once Docker is installed, you need to add your user to the docker group with the command:

sudo usermod -aG docker $USER

Log out and log back in so the changes will take effect.

With Docker taken care of, install docker-compose with the following commands:

curl -L`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

Next we must install NGINX. If your instance of Ubuntu Server still has Apache installed, stop and disable it with the commands:

sudo systemctl stop apache2
sudo systemctl disable apache2

Install NGINX with the command:

sudo apt-get install nginx

Start and enable NGINX with the commands:

sudo systemctl start nginx
sudo systemctl enable nginx

Download the Harbor installer

Next we need to download the Harbor offline installer with the command:


Once that file has downloaded, extract it with the command:

tar xvzf harbor-offline-installer-v1.8.1.tgz

This will create a new directory, called harbor. Change into that directory with the command:

cd harbor

Generating the SSL Keys

In order for Harbor to function properly, you'll need to set it up to use SSL. In a production environment you must use certificates from a trusted Certificate Authority. For a testing environment you can work with self-signed certificates. Here are the steps to generate the self-signed certificates.

Generate the self-signed certificates with the command:

openssl req -newkey rsa:4096 -nodes -sha256 -keyout ca.key -x509 -days 3650 -out ca.crt

Generate the signing request with the command:

openssl req -newkey rsa:4096 -nodes -sha256 -keyout -out

Note: Substitute the above IP address with either your server domain or server IP address.

Create a configuration file for the Subject Alternate name with the command:

nano extfile.cnf

In that file, paste the following contents:

subjectAltName = IP:

Again, substitute the IP address of your Harbor server for

Generate the certificate with the command:

openssl x509 -req -days 3650 -in -CA ca.crt -CAkey ca.key -CAcreateserial -extfile extfile.cnf -out

Once again, substitute the above IP address with either your server domain or server IP address.

Create the client certificate with the command:

openssl req -new -x509 -text -key ca.key -out ca.cert

Copy the newly-generated certificates into the proper directory with the command:

sudo cp *.crt *.key *.cert /etc/docker/certs.d/

Make sure to substitute the IP address above with the IP address of your Harbor server. If you find that the /etc/docker/certs.d directory doesn't exist, create it with the command:

sudo mkdir /etc/docker/certs.d

You will probably also have to create the IP address subdirectory in the same fashion.

Configure the installer

Before we run the installation, there are a few configurations to be taken care of. Open the configuration file with the command:

nano harbor.yml

In that file, you need to edit the following options:

  • hostname - set this to either the IP address or the domain of your hosting server.
  • port - set this to 8080.
  • harbor_admin_password - set this to a strong, unique password.
  • password (in the database configuration section) - change this to a strong, unique password.

It is also necessary to uncomment the following SSL lines, making sure to edit them to reflect the changes below:

port: 443
certificate: /etc/ssl/certs/ca.crt
private_key: /etc/ssl/certs/ca.key

Make sure to change the path to the SSL certificates to:

certificate: /etc/docker/certs.d/
  private_key: /etc/docker/certs.d/

Save and close that file.

Installing Harbor

It's time to run the installer script. We'll be installing Harbor with Clair support. Without Clair support installed, you won't be able to scan images for vulnerabilities, which is part of the point of using Harbor. From within the harbor directory, issue the command:

sudo ./ --with-clair

The installation will take some time, but should complete without error.

Logging in

With the installation complete, you can then point a web browser to https://SERVER_IP (where SERVER_IP is the IP address of your Harbor server). You will be presented with a login screen, where you'll use admin as the user and the password you configured for harbor_admin_password. Once logged in, you are ready to start using your Harbor registry.

Three caveats

I ran into a few issues during the installation—most of which I've resolved with the instructions above. However, if you are working with an instance of Ubuntu Server that already had docker installed with deployed containers, you might receive a warning that the necessary port is in use. If that's the case, you can stop and delete all running containers with the following commands:

docker kill $(docker ps -q)
docker rm $(docker ps -a -q)

With those existing containers stopped and removed, run the installer again to see it complete without problems.

The next caveat is all about self-signed certificates. If you opt to go that route, you'll need to modify the /etc/ssl/openssl.cnf file, before generating the certificates. Open that file for editing with the command:

sudo nano /etc/ssl/openssl.cnf

In that file, locate the [v3_ca] section and add the following line:

subjectAltName = IP:

Make sure to change the IP address to that of your Harbor server. Save and close that file and then generate your self-signed certificates.

Finally, watch for the following error when trying to login to your new registry:

Error saving credentials: error storing credentials - err: exit status 1, out: `Cannot autolaunch D-Bus without X11 $DISPLAY`

You can resolve this by installing two applications with the following command:

sudo apt install gnupg2 pass

Happy Harboring

You are now ready to start working with your own on-premises docker registry—one that offers security and vulnerability analysis on your content.

Also see