How to Install Harbor 2.16 on AlmaLinux 9 or Rocky Linux 9
Install Docker Engine, configure harbor.yml with HTTPS, run the Harbor 2.16 installer on AlmaLinux 9 or Rocky Linux 9 and push a first image.
This guide installs Harbor 2.16, the open source container registry from the Cloud Native Computing Foundation, on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9. At the end you will have a private registry at https://harbor.example.com with a web portal, projects and user accounts, and you will have pushed a first image to it.
CentOS 7 reached end of life in June 2024. Harbor runs as a set of Docker containers, so it works on any current Linux host with Docker Engine; the RHEL 9 family is the direct replacement for a CentOS 7 server.
Requirements
Harbor's installation prerequisites are higher than many older tutorials suggest:
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| Memory | 4 GB | 8 GB |
| Disk | 40 GB | 160 GB |
- Docker Engine newer than 20.10 with the Docker Compose plugin newer than 2.3.
- A DNS name, here
harbor.example.com, that points to the server's public IP address. - Ports 80 and 443 free on the host. Harbor's own proxy container binds to both.
- A user with
sudorights.
Step 1: Install Docker Engine
Docker publishes packages for CentOS Stream 9 and RHEL 9. AlmaLinux 9 and Rocky Linux 9 are not on Docker's list of tested platforms, but they are binary compatible with RHEL 9 and use the CentOS repository without changes. Add the repository and install the engine with the Compose plugin:
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Start Docker now and at every boot, then check both components:
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
The standalone docker-compose Python package that older tutorials install with pip is obsolete. Harbor's installer uses the docker compose plugin.
Step 2: Open the firewall
Allow HTTP and HTTPS through firewalld:
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload
Step 3: Get a TLS certificate
Docker clients refuse to talk to a plain-HTTP registry unless every client is reconfigured with an insecure-registries entry, so set up HTTPS from the start. Harbor only needs the paths to a certificate (including the intermediate chain) and its private key. Any certificate for your host name works. To get a free one from Let's Encrypt before Harbor occupies port 80, install Certbot from EPEL and use its standalone mode:
sudo dnf install -y epel-release
sudo dnf install -y certbot
sudo certbot certonly --standalone -d harbor.example.com
Certbot stores the files in /etc/letsencrypt/live/harbor.example.com/ as fullchain.pem and privkey.pem.
A self-signed certificate is possible, but then the CA certificate has to be copied to /etc/docker/certs.d/harbor.example.com/ on every Docker client. The Harbor documentation describes that procedure in its HTTPS section.
Step 4: Download the Harbor installer
Harbor releases are published on the project's GitHub releases page. Each release has an online installer, which pulls the images from the internet during installation, and a much larger offline installer that contains them. Since version 2.16.0 the archives are built per architecture (amd64 and arm64). Download the online installer and unpack it into /opt:
cd /tmp
curl -fLO https://github.com/goharbor/harbor/releases/download/v2.16.0/harbor-online-installer-v2.16.0-amd64.tgz
sudo tar xzvf harbor-online-installer-v2.16.0-amd64.tgz -C /opt
This creates /opt/harbor with the installer script, the prepare script and a configuration template. The release page also carries an md5sum file and a Sigstore bundle for each archive if you want to check the download.
Step 5: Configure harbor.yml
Copy the template and open the new file:
cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo vi harbor.yml
Change the following settings near the top of the file and leave the rest at their defaults:
hostname: harbor.example.com
http:
port: 80
https:
port: 443
certificate: /etc/letsencrypt/live/harbor.example.com/fullchain.pem
private_key: /etc/letsencrypt/live/harbor.example.com/privkey.pem
harbor_admin_password: ChangeThisAdminPassword
database:
password: ChangeThisDatabasePassword
data_volume: /data
hostnamemust be the name clients use. Do not uselocalhostor127.0.0.1.harbor_admin_passwordis only applied on the first start. The template value isHarbor12345; replace it before you install.database.passwordis the password of the bundled PostgreSQL database. The template ships with a placeholder that you must change for production. Keep the other keys of thedatabaseblock as they are in the template.data_volumeis where images, the database and other state are stored on the host. Put it on the disk with the most space.
Step 6: Run the installer
Run the installer as root. Adding --with-trivy also deploys the Trivy scanner so that Harbor can scan images for known vulnerabilities:
cd /opt/harbor
sudo ./install.sh --with-trivy
The script checks Docker and Compose, generates the configuration under /opt/harbor/common, pulls the images and starts the containers. When it finishes, list them:
sudo docker compose ps
Every service should be up and marked (healthy) after a minute or two.
Step 7: Sign in and push an image
Open https://harbor.example.com in a browser and sign in as admin with the password from harbor.yml. Create a normal user for daily work under Administration > Users, and create projects for your images. A public project named library exists by default.
From any machine with Docker, log in, tag an image with the registry name and project, and push it:
docker login harbor.example.com
docker pull hello-world
docker tag hello-world harbor.example.com/library/hello-world:latest
docker push harbor.example.com/library/hello-world:latest
The image appears in the portal under Projects > library > Repositories.
Managing the installation
Harbor is controlled with Docker Compose from the installation directory. The containers use a restart policy, so they come back after a reboot as long as the Docker service is enabled.
cd /opt/harbor
sudo docker compose stop
sudo docker compose start
After you edit harbor.yml, or after the TLS certificate has been renewed, regenerate the configuration and recreate the containers. Image data stays on disk in data_volume:
cd /opt/harbor
sudo ./prepare --with-trivy
sudo docker compose down -v
sudo docker compose up -d
Back up the data_volume directory and harbor.yml together. For upgrades, follow the upgrade guide in the Harbor documentation for your source and target versions, because the database schema is migrated on the way.
Frequently asked questions
How do I renew the Let's Encrypt certificate while Harbor is running?
Certbot's standalone mode needs port 80, which Harbor's proxy holds. Either stop Harbor for the renewal (sudo docker compose stop, sudo certbot renew, then start it again) or switch to a DNS-based challenge that needs no open port. In both cases run ./prepare and recreate the containers afterwards so that Harbor picks up the new files.
Should I use the online or the offline installer?
They install the same software. The online installer is a small download and pulls images from the internet during install.sh. Choose the offline installer when the server has no outbound internet access or when you want a reproducible package to install several hosts.
Can Harbor run on a 1 GB server?
Not reliably. Harbor starts around ten containers, including PostgreSQL, a cache, the registry, the core API and the job service. The documented minimum is 2 CPU cores and 4 GB of memory, and the Trivy scanner adds to that when it runs.
Why does docker login fail with an x509 certificate error?
The client does not trust the certificate chain. With a public CA, make sure certificate in harbor.yml points to the full chain rather than only the server certificate. With a private or self-signed CA, install the CA certificate on each client under /etc/docker/certs.d/harbor.example.com/ and restart Docker.