Workload · Running a container registry

A self-hosted Harbor registry on a server of your own

Self-hosting the Harbor registry takes one Linux machine with Docker Engine and the Compose plugin, at least 2 CPU cores, 4 GB of memory and 40 GB of disk (the project recommends 4, 8 and 160), a hostname and a TLS certificate; the installer starts every component as containers. Below: sizing, the install, scanning, reclaiming disk and upgrading safely.

The short version
  1. Harbor's own floor: 2 cores, 4 GB, 40 GB; recommended 4 cores, 8 GB, 160 GB
  2. Online installer pulls images; offline bundle carries them
  3. Trivy scanning needs the --with-trivy option, at install or on a later reconfigure
  4. Deleting images frees nothing until garbage collection runs

What Harbor asks of the machine

Harbor needs little compute and as much disk as your images take. The project's floor and recommendation, for the Docker Compose install described here:

ResourceMinimumRecommended
CPU2 cores4 cores
Memory4 GB8 GB
Disk40 GB160 GB

On the software side it wants Docker Engine newer than 20.10 and Docker Compose newer than 2.3 (the plugin that ships with Docker Engine), plus OpenSSL if you will make certificates yourself. The portal and API answer on 443 for HTTPS and 80 for HTTP, both changeable in the config file.

The disk figure is the one to think hard about. Every layer of every image you push lands under data_volume, which defaults to /data, and the PostgreSQL database that tracks them lives there too. Build pipelines that push a new tag on every commit can fill 160 GB well before the processor is busy.

Why a whole machine suits a registry

A registry is mostly disk and network: CI runners push layers, clusters pull them, and a busy morning moves a lot of bytes both ways. Our storage servers put your data on a bare metal machine whose port nobody else shares at the access switch, and nothing meters the traffic, so a fleet of nodes pulling a fresh image at once never becomes a transfer bill.

You also choose how the drives are laid out, balancing speed, capacity and safety, and a storage consultant on chat will help pick the RAID level. When the registry fills up, disks and memory can be added to the machine you already have, with no migration and no new IP address.

The server that fits

Start from the dedicated storage servers page: that is the line built for this job. Going by Harbor's own numbers, aim for at least 8 GB of memory and four cores, then spend the rest on drives.

  • A small team registry: any machine above Harbor's recommendation with a mirrored pair of SSDs, so one dead drive does not take your images with it.
  • Many pipelines and clusters: a blade or rack line, where a hardware RAID controller takes more drives in RAID 5, 6 or 10 (depending on the controller) and the iLO, iDRAC or BMC console reaches the machine even if its network settings break. The m510, m710x and m750 cartridges use software RAID instead.
  • Close to your builders: pick the city nearest your CI runners and clusters, from New York, Miami, San Francisco, Amsterdam or Bucharest.

Every line is on the dedicated server catalogue, with root access, the control panel and 24/7 support by phone or live chat. A racked machine goes live in about 30 minutes once the order is approved; a built-to-order one takes longer.

Up and running in an evening

Harbor ships two installers on its GitHub releases page. The online one is small and pulls Harbor's images from Docker Hub during the install; the offline one carries them inside, so it is larger but works where Docker Hub is out of reach. Pick a hostname first: Harbor's documentation says not to use localhost, 127.0.0.1 or 0.0.0.0, because clients on other machines must be able to reach it.

  1. Install a supported Linux image when you order, then install Docker Engine with the Compose plugin from Docker's own repository, following Docker's install guide for your distribution.
  2. Point a DNS name, for example reg.yourdomain.com, at the server's IP address and obtain a certificate for it from a trusted authority. Harbor ships with no certificates, and its documentation calls a CA-signed certificate the recommended approach for production.
  3. Make the certificate folder with sudo mkdir -p /data/cert/ and copy your certificate and key into it.
  4. Download the installer and its .asc signature from the releases page, then check the signature and unpack it. Replace version with the release you downloaded, and online with offline if you took the larger bundle. The archive is only unpacked if the signature checks out:
gpg --keyserver hkps://keyserver.ubuntu.com --receive-keys 644FF454C0B4115C
gpg -v --keyserver hkps://keyserver.ubuntu.com --verify harbor-online-installer-version.tgz.asc && tar xzvf harbor-online-installer-version.tgz

Inside the new harbor folder, copy harbor.yml.tmpl to harbor.yml and edit it. These are the lines that matter on day one; the two passwords must be long ones of your own:

hostname: reg.yourdomain.com
http:
  port: 80
https:
  port: 443
  certificate: /data/cert/yourdomain.com.crt
  private_key: /data/cert/yourdomain.com.key
harbor_admin_password: CHANGE_ME_ADMIN
database:
  password: CHANGE_ME_DB
data_volume: /data

Lock the admin account before you start. The template ships Harbor12345 as the admin password and root123 for the database. The admin value is read only on the first start, so whatever the file holds then is what anyone reaching port 443 can sign in with. Set both first, and leave Allow Self-Registration off (its default).

Then run sudo ./install.sh --with-trivy from the harbor folder. Drop --with-trivy if you do not want vulnerability scanning; it can be added later by stopping Harbor and rerunning sudo ./prepare --with-trivy, as Harbor's reconfigure guide shows. Open https://reg.yourdomain.com, sign in as admin, create a project, and push from any Docker client with docker login reg.yourdomain.com.

If you sign with your own CA, each Docker client needs that CA's certificate under /etc/docker/certs.d/reg.yourdomain.com/, then systemctl restart docker. Plain HTTP forces every client to list Harbor as an insecure registry: fine in a lab, wrong anywhere else.

Scanning images before they ship

With Trivy installed, Harbor can scan an image on demand, scan everything on a schedule, or scan each image the moment it is pushed. That last one is a per-project setting: open the project, then its Configuration tab, and tick automatic scanning on push.

The same tab has Prevent vulnerable images from running. Pick a severity and Harbor refuses to serve any image whose findings reach it, so a cluster cannot pull it. Turn it on for the projects production pulls from, and keep scratch projects looser.

Trivy keeps its vulnerability database up to date by downloading it. On a machine without outside access, skip_update: true in the trivy block stops that, and you supply the database files yourself.

Getting disk space back

Deleting an image in Harbor removes the record, not the bytes. Layers stay on disk until garbage collection removes blobs no manifest references. Under Administration, Clean Up, Garbage Collection you can run it now or schedule it (hourly, daily, weekly or by cron), with a dry run first to see what it would free.

  • Current releases keep pushes and pulls working while it runs, so a nightly schedule does not lock your users out.
  • Anything written in the last two hours is left alone, which protects uploads still in progress.
  • The option to delete untagged artifacts removes images whose tags were overwritten, which builds up quickly when CI pushes the same tag over and over.

Keeping it healthy: backups and upgrades

Everything Harbor stores sits under data_volume, which survives containers being removed and recreated. That lets you recreate the containers without losing images, but it is not a backup: one machine is one copy. Copy /data and your harbor.yml off the server on a schedule, with Harbor stopped (sudo docker compose down from the harbor folder, then sudo docker compose up -d afterwards), because PostgreSQL's files are only a usable backup when copied while the database is shut down. A restore needs both the images and the database that indexes them.

Before every upgrade, Harbor's guide says to stop the instance, move the old installer folder aside and copy the database. Run this as root (for example after sudo -i) from the folder that contains harbor; each step runs only if the previous one succeeded, and nothing is deleted:

mkdir -p /my_backup_dir && cd harbor && docker compose down && cd .. && mv harbor /my_backup_dir/harbor && cp -r /data/database /my_backup_dir/

Then unpack the new release, put your old harbor.yml in it, convert it with the migrator from the matching goharbor/prepare image, and run sudo ./install.sh --with-trivy again (keep the flag if you installed with it). The upgrade guide says which releases it upgrades from; older installs step through a migration guide first. Pulls fail while Harbor is down, so pick a quiet hour.

Docker publishes Harbor's ports past ufw: Docker's own documentation says traffic to published container ports is routed before ufw rules apply. Do not rely on a ufw rule to hide the portal. Harbor's login is the gate, so strong passwords and a closed self-registration are what protect it.

When this is the wrong place for it

The Compose install runs Harbor on one machine. While it is down for an upgrade or a fault, nothing can push or pull, so clusters that must scale at any hour need a second registry to fall back on or a highly available design of your own.

If you already run Kubernetes you may prefer Harbor inside it: managed Kubernetes on bare metal gives you the cluster, and Kubernetes you run yourself covers the do-it-all route. And for a handful of private images on one project, Harbor's database, job service and scanner may be more than the job needs.

Questions people ask

Should I pick the online or the offline installer?
The online installer is small and pulls Harbor's container images from Docker Hub while it installs, so the machine needs to reach Docker Hub. The offline bundle includes those images and is larger, which suits servers with restricted outbound access or slow links. Both are installed with the same install.sh script.
Can I add vulnerability scanning after installing without it?
Yes. From the harbor folder, stop Harbor with sudo docker compose down -v (Harbor's docs say this keeps the image data and database files), run sudo ./prepare --with-trivy, then start it again with sudo docker compose up -d. Keep the flag on every later install or upgrade so scanning stays on.
Can I add disks to my registry server later?
Yes. Memory, disks and port speed can be added to the server you already have, without moving to a new machine or changing its IP address. Growing the filesystem that holds Harbor's data volume onto the new disks is then up to you.
Do I need a contract to run a registry here?
No. Servers are billed month to month by default, with no long-term contract. Prices for each storage configuration are on the order page, not on this one.

Get a server for your Harbor registry

Pick a storage server, choose the drives and RAID layout with a consultant if you like, and have your images on a machine whose disks and port are yours alone.

Choose a storage server

Read next