VPS Tutorials
Harbor on a VPS: verified installers, Trivy and tested recovery
Install Harbor 2.15.5 with Sigstore verification and HTTPS. Scope CI robot permissions, test scan and retention policies, schedule garbage collection, and rehearse encrypted off-host recovery.

After a team starts using docker build, image storage becomes an operational dependency. A personal Docker Hub account complicates permissions, rate limits and handover; a bare registry:2 is lighter but does not supply Harbor's project roles, robot accounts, scanning, audit, retention and replication features.
This guide covers an Ubuntu 24.04 VPS, Compose, trusted HTTPS and Trivy. The September 3, 2026 example used Harbor v2.15.2. The official release checked on November 16 is v2.15.5, published November 12. Its installer assets use Sigstore bundles, so the historical .asc/GPG commands below are not the verification path for the current package. Use the current pinned download and verification instructions before installation.
- Separate private image projects for several teams.
- Give CI project-specific push access and production pull-only access.
- Scan uploaded images for known CVEs.
- Retain
release-*while expiring development builds. - Audit image pushes, deletions and access.
- Replicate artifacts to another registry or location.
| Option | Resources | Access and audit | Scanning | Fit |
|---|---|---|---|---|
| Plain registry | Low | Assemble separately | No integrated scanner | Individual use and small caches |
| Harbor | Moderate/high | Projects, roles and robot accounts | Trivy integration | Teams and self-hosted CI |
| GitLab registry | Part of GitLab operations | GitLab project permissions | Edition-dependent | Existing GitLab installations |
| Managed registry | No registry host to maintain | Provider controls | Plan-dependent | Acceptable provider and traffic costs |
An existing GitLab CE registry and runner may be simpler. Harbor is useful across several CI/Git platforms rather than requiring one platform.
The original official sizing baseline is 2 CPU cores, 4GB RAM and 40GB disk, with 4 cores/8GB/160GB recommended. Trivy databases and scans add CPU, RAM and I/O demand.
| Use | Starting resources | Conditions |
|---|---|---|
| Laboratory/personal | 2 vCPU, 4GB, 80GB SSD | Limit scans and historical tags |
| Team of 3–10 | 4 vCPU, 8GB, 160GB SSD | Trivy and explicit retention |
| Frequent multi-project CI | 8 vCPU, 16GB, separate data disk | Space for a full backup/upgrade |
| Multi-location production | Independent database/storage or instances | Outside this single-host guide |
Shared image layers save space, but architectures, old tags, scanner databases, PostgreSQL, job logs and backups also grow. A 160GB disk is tight when 100GB of artifacts must be backed up locally.
Use /data as a dedicated Harbor volume, preferably expandable SSD/block storage. On a shared host choose an isolated directory and update every data/backup path accordingly; do not archive unrelated applications. Verify that provider snapshots include the data disk.
Point harbor.example.com to the VPS. Publish AAAA only with working IPv6.
| Port | Purpose | Access |
|---|---|---|
22/TCP | Administration | SSH keys and restricted sources |
80/TCP | HTTP-01 and redirects | Public when using this certificate method |
443/TCP | Portal, API, push/pull | Intended registry clients |
Keep PostgreSQL, Redis, Registry and Jobservice internal. Diagnose client timeouts through DNS, listener, firewall and security-group checks.
Install Docker Engine and Compose v2 from the official Ubuntu repository. Use docker compose, keeping the legacy docker-compose executable separate:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl gnupg jq certbot dnsutils
docker version
docker compose version
openssl version
The original prerequisites require Engine above 20.10 and Compose above 2.3; check the target release's current prerequisites too. Review system upgrades/reboots and the production Compose checklist.
Check that DNS and the host's public address agree:
dig +short harbor.example.com A
curl -4 ifconfig.me
NAT or multi-address hosts require checking the intended inbound address rather than assuming the outbound address identifies it. Standalone Certbot needs 80 free:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo certbot certonly --standalone \
-d harbor.example.com \
--agree-tos \
-m [email protected] \
--no-eff-email
Replace domain/email. The certificate paths are:
/etc/letsencrypt/live/harbor.example.com/fullchain.pem
/etc/letsencrypt/live/harbor.example.com/privkey.pem
Use a trusted CA for cross-network clients. insecure-registries is not a solution to a broken public TLS chain.
These retained v2.15.2 commands describe the older example, including its requested .asc file. For the checked v2.15.5 release, proceed to the Sigstore procedure below instead:
cd /tmp
HARBOR_VERSION=v2.15.2
curl -fLO \
"https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz"
curl -fLO \
"https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz.asc"
This procedure applies only to a package actually accompanied by the corresponding authentic GPG signature and a independently verified signing-key fingerprint:
gpg --keyserver hkps://keyserver.ubuntu.com \
--receive-keys 644FF454C0B4115C
gpg --verify \
"harbor-online-installer-${HARBOR_VERSION}.tgz.asc" \
"harbor-online-installer-${HARBOR_VERSION}.tgz"
Do not treat a missing .asc file as permission to skip verification or use this old short key identifier to verify a Sigstore bundle.
Install a supported cosign release using the official Sigstore instructions. Keep the installer in a persistent directory:
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/harbor-installers/v2.15.5
cd /opt/harbor-installers/v2.15.5
HARBOR_VERSION=v2.15.5
curl -fLO "https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz"
curl -fLO "https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz.sigstore.json"
printf '%s\n' '6b3aa89c868d975549be7dad7238bf1f674fc248711a0913b42d65832f589b7d harbor-online-installer-v2.15.5.tgz' | sha256sum -c -
cosign verify-blob \
--bundle "harbor-online-installer-${HARBOR_VERSION}.tgz.sigstore.json" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity "https://github.com/goharbor/harbor/.github/workflows/publish_release.yml@refs/tags/${HARBOR_VERSION}" \
"harbor-online-installer-${HARBOR_VERSION}.tgz"
The digest and workflow identity come from the checked release asset/bundle. For future versions, obtain that version's digest, bundle and expected identity independently; do not reuse this digest or relax identity checks. The online installer downloads component images during installation; the matching offline installer includes them.
Confirm /opt/harbor does not already contain an installation. After successful package verification:
sudo tar -xzf "harbor-online-installer-${HARBOR_VERSION}.tgz" -C /opt
sudo chown -R root:root /opt/harbor
cd /opt/harbor
ls -la
Keep the versioned download directory and installed configuration for recovery and upgrades.
Copy certificates to stable paths rather than relying on Certbot symlinks:
sudo install -d -m 700 /data/cert
sudo cp \
/etc/letsencrypt/live/harbor.example.com/fullchain.pem \
/data/cert/harbor.crt
sudo cp \
/etc/letsencrypt/live/harbor.example.com/privkey.pem \
/data/cert/harbor.key
sudo chmod 600 /data/cert/harbor.crt /data/cert/harbor.key
Generate different initial administrator/database passwords:
openssl rand -base64 32
openssl rand -base64 32
One is for admin, the other PostgreSQL. Replace Harbor12345 and keep both in restricted team secret storage.
Use the selected release's template:
cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo chmod 600 harbor.yml
sudoedit harbor.yml
Edit only required values in the new harbor.yml. The two password placeholders below mean the first/second generated secrets and must be replaced completely:
hostname: harbor.example.com
http:
port: 80
https:
port: 443
certificate: /data/cert/harbor.crt
private_key: /data/cert/harbor.key
harbor_admin_password: 替换为第一段随机密码
database:
password: 替换为第二段随机密码
data_volume: /data
trivy:
ignore_unfixed: false
skip_update: false
offline_scan: false
insecure: false
log:
level: info
local:
rotate_count: 10
rotate_size: 200M
location: /var/log/harbor
hostnameis the hostname withouthttps://.certificateandprivate_keyare absolute host paths.data_volumestores registry, database, Redis and scanner data.skip_update: falsepermits vulnerability database updates.- Quote special-character passwords according to YAML/current template rules.
Check for defaults:
sudo grep -nE 'Harbor12345|root123' /opt/harbor/harbor.yml
There should be no matches. harbor.yml contains credentials and belongs outside public repositories.
Verify 80/443 are free:
sudo ss -lntp | grep -E ':(80|443)\b' || true
An existing web server needs a separate IP/host or a planned shared proxy using the correct external_url. Install explicitly with the scanner:
cd /opt/harbor
sudo ./install.sh --with-trivy
--with-trivy enables Trivy; plain install.sh does not. Check services/routes:
cd /opt/harbor
sudo docker compose ps
curl -fsS https://harbor.example.com/api/v2.0/health | jq
curl -sSI https://harbor.example.com/v2/ | head
Health should report healthy. Unauthenticated /v2/ returning 401 Unauthorized is the expected registry challenge, not authenticated acceptance. Inspect errors:
cd /opt/harbor
sudo docker compose logs --tail=200
sudo find /var/log/harbor -maxdepth 1 -type f -printf '%f\n' | sort
Open https://harbor.example.com with admin and the initial password from harbor.yml:
- Store the administrator secret in the team's password manager.
- Disable open registration unless it is intentional.
- Assign developers only the required project roles.
- Create private projects instead of using
libraryfor everything. - Set project quotas.
- Check Trivy availability and database freshness.
- Configure audit retention and external alerts.
Private projects require membership/authorized robots; public projects allow anonymous pulls and are unsuitable for internal images.
Create private project demo first. Log in:
docker login harbor.example.com
Test the round trip:
docker pull alpine:3.22
docker tag alpine:3.22 harbor.example.com/demo/alpine:3.22
docker push harbor.example.com/demo/alpine:3.22
docker pull harbor.example.com/demo/alpine:3.22
Use a project-qualified path:
harbor.example.com/<project>/<repository>:<tag>
docker login can store credentials in ~/.docker/config.json. Configure a credential helper and appropriate permissions, particularly on shared machines.
In the project's Configuration:
- Enable automatic scanning on push.
- Decide whether to prevent vulnerable-image pulls.
- Set a tested threshold such as
Critical. - Use expiring exceptions for reviewed CVEs that cannot yet be fixed.
Harbor enforces registry pull policy; it does not stop an already-running image or replace workload admission controls. Test Critical blocking before applying it to production, where a later restart could otherwise fail to pull. Schedule rescans as vulnerability data changes and monitor database-update failures. Limit scanner/CI concurrency on 4GB hosts.
Create a robot through:
Projects → demo → Robot Accounts → New Robot Account
Give ci-push only the required demo permissions:
- Repository Pull.
- Repository Push.
- Artifact Read.
- Scan permission only when the pipeline triggers scans itself.
Set expiry, for example 90 days according to team policy. Save the actual generated username/one-time secret; never guess its prefix or grant cross-project system access unnecessarily.
printf '%s' "$HARBOR_ROBOT_SECRET" | \
docker login harbor.example.com \
--username "$HARBOR_ROBOT_USER" \
--password-stdin
docker logout harbor.example.com
Store the robot as a Username with password credential and use Jenkinsfile:
pipeline {
agent { label 'linux' }
environment {
REGISTRY = 'harbor.example.com'
IMAGE = 'harbor.example.com/demo/webapp'
}
stages {
stage('Build') {
steps {
sh 'docker build -t "$IMAGE:$BUILD_NUMBER" .'
}
}
stage('Push') {
steps {
withCredentials([usernamePassword(
credentialsId: 'harbor-demo-robot',
usernameVariable: 'HARBOR_USER',
passwordVariable: 'HARBOR_SECRET'
)]) {
sh '''
set +x
printf '%s' "$HARBOR_SECRET" | \
docker login "$REGISTRY" \
--username "$HARBOR_USER" \
--password-stdin
docker push "$IMAGE:$BUILD_NUMBER"
docker logout "$REGISTRY"
'''
}
}
}
}
}
Use an isolated build agent, not the controller's host Docker socket; see the Jenkins deployment guide. Put logout/temporary credential-directory cleanup in an always-executed post step so failed pushes also clean up. Separate environment accounts:
ci-pushfor build/push.staging-pullfor staging pulls.prod-pullfor production pulls.- Separate secrets, expirations and rotation owners.
Production should not reuse ci-push push permissions.
Design and dry-run project retention:
- Keep required
release-*releases. - Retain, for example, the newest 20
main-*builds. - Retain five recent development builds per branch.
- Do not make mutable
latestthe only rollback reference.
Record deployed digests and protect artifacts still in use:
docker inspect \
--format='{{index .RepoDigests 0}}' \
harbor.example.com/demo/webapp:42
Retention selects artifacts; it neither frees every shared layer immediately nor replaces backups/replication.
Under Administration → Clean Up → Garbage Collection:
- Run DRY RUN.
- Review eligible blobs and space.
- Check push, retention and replication jobs.
- Run GC or schedule it.
- Review GC history and job logs.
The original documented safety window protects recently uploaded layers for two hours; check the selected version's behavior. Act before disk exhaustion and use 70%/85% alerts:
df -h
sudo du -xhd1 /data | sort -h
sudo du -xhd2 /data/registry | sort -h | tail -30
cd /opt/harbor && sudo docker compose ps
The core data_volume is /data, with configuration in /opt/harbor. /opt/harbor/docker-compose.yml alone contains neither image blobs nor the metadata database. Enable Read Only, wait for active push/scan/replication/GC jobs to finish, then stop services:
cd /opt/harbor
sudo docker compose ps
sudo docker compose down
Create the stopped-state archive:
sudo install -d -m 700 /backup/harbor
sudo tar --xattrs --acls \
-C / \
-czf "/backup/harbor/harbor-$(date +%F-%H%M%S).tar.gz" \
data \
opt/harbor
sudo sha256sum /backup/harbor/harbor-*.tar.gz
Large /data archives need additional disk. A consistent storage snapshot or encrypted restic backup of /data and /opt/harbor to independent storage may be better; see backup/recovery practice. Restart and disable Read Only only after validating backup success:
cd /opt/harbor
sudo docker compose up -d
curl -fsS https://harbor.example.com/api/v2.0/health | jq
Preserve:
- Complete
/datadata. /opt/harbor/harbor.yml, installer and versioned download material.- Generated Compose/configuration.
- TLS files or a tested reissue procedure.
- Version and
--with-trivyinstallation parameters. - Robot reissue and CI secret-update procedures.
- Read-only/recovery checklist.
Encrypt archives and keep them outside the registry's own failure domain.
Use an isolated VPS, at least quarterly according to recovery requirements:
- Match backed-up Docker/Harbor versions.
- Stop the empty destination.
- Restore
/data//opt/harbor, ownership, ACLs and attributes. - Verify
harbor.ymldomain, certificate paths and secrets. - Run
sudo ./prepare --with-trivy. - Run
sudo docker compose up -d. - Check Portal,
/api/v2.0/healthand/v2/. - Authenticate, pull a private image and verify its digest.
- Check projects, robots, scans, policies and audit history.
- Record recovery time and missing items.
Restore the original version before attempting a major upgrade.
Harbor occupies 80/443; standalone renewal needs a maintenance window to free 80:
cd /opt/harbor
sudo docker compose down
sudo certbot renew --standalone
sudo cp \
/etc/letsencrypt/live/harbor.example.com/fullchain.pem \
/data/cert/harbor.crt
sudo cp \
/etc/letsencrypt/live/harbor.example.com/privkey.pem \
/data/cert/harbor.key
sudo chmod 600 /data/cert/harbor.crt /data/cert/harbor.key
sudo ./prepare --with-trivy
sudo docker compose up -d
Check renewed validity:
echo | openssl s_client \
-connect harbor.example.com:443 \
-servername harbor.example.com 2>/dev/null | \
openssl x509 -noout -issuer -dates
Automate failure handling so Harbor restarts even if renewal fails, and test the renewal procedure. DNS-01 or independently managed proxy certificates can avoid this downtime when configured for the actual DNS provider.
Upgrades can migrate harbor.yml and database schema:
- Read release notes, compatibility and migration guidance.
- Check supported upgrade hops.
- Back up
/data, database and installation files. - Test migration/rollback on a copy.
- Record scanner, storage, identity and replication configuration.
- Schedule downtime.
The target installer/prepare image goharbor/prepare:<tag> migrates harbor.yml; Harbor Core handles supported database migration after backing up /data/database. Unsupported downgrades cannot be fixed by changing a tag: retain pre-upgrade database and /data copies.
For docker login and x509: certificate signed by unknown authority:
echo | openssl s_client \
-connect harbor.example.com:443 \
-servername harbor.example.com \
-showcerts
Check cert.pem versus fullchain.pem, client CA trust and DNS. Do not hide it with insecure-registries.
For 413 Request Entity Too Large, inspect CDN/WAF/outer proxy on 443. Check upload limits/timeouts; generated edits disappear after prepare.
df -h
sudo du -sh /data/registry /data/database /data/trivy-adapter 2>/dev/null
cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=200 proxy core registry jobservice
Check disk, inodes, routes, loss, timeouts and writes to /data/registry.
cd /opt/harbor
sudo docker compose logs --tail=200 trivy-adapter
date -Is
curl -I https://github.com
Check outbound DNS, clock, proxy and registry/database-source rate limits. Use the supported offline database procedure; skip_update: true with permanently stale data does not establish safety.
Check retention and shared manifests, then GC dry-run. Never manually delete /data/registry/docker/registry/v2/blobs.
Check expiry, disabled state, rotated secret and exact username. Updating a Harbor robot does not update Jenkins/GitHub secrets automatically.
cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=200
sudo journalctl -u docker --since '30 minutes ago' --no-pager
free -h
df -h
Inspect OOM/exit evidence, then reduce scans or add RAM.
prepare/prepare regenerate files from harbor.yml. Keep supported settings in harbor.yml; maintain extra proxy components separately.
- Pin the reviewed installer patch.
- Verify the actual signature format and package.
- Meet CPU/RAM/storage requirements with backup headroom.
- Put
/dataon expandable/snapshot-capable storage. - Validate DNS A/AAAA.
- Use trusted HTTPS for Portal/Registry.
- Remove defaults from
harbor.ymland keep mode600. - Keep internal ports private.
- Install
--with-trivyand verify scanner freshness. - Use private projects and quotas.
- Test automatic push scanning.
- Test pull-block thresholds in a safe project.
- Give CI project robots rather than
admin. - Separate push and production pull accounts.
- Monitor robot rotation/expiry.
- Dry-run retention.
- Schedule/review GC.
- Enable 70%/85% disk alerts.
- Encrypt off-host
/data//opt/harborbackups. - Test private pull/digest recovery.
- Rehearse certificate renewal.
- Follow supported backup/migration upgrades.
2 cores/4GB/40GB is the historical official floor; 4 cores/8GB/160GB with independent storage is a more useful small-team starting point, measured against scans and image growth.
A registry stores artifacts; Harbor adds project RBAC, robots, scanning, audit, replication, retention and GC at a higher operating cost.
Use it across networks. insecure-registries weakens client transport trust; HTTP belongs to deliberate isolated experiments.
Shared layers remain referenced; GC removes eligible unreferenced blobs after reviewing retention and active deployments.
An expiring project push robot, never admin. Use a separate pull-only production robot.
/data/registry alone omits metadata/permissions. Restore consistent /data and /opt/harbor with certificates and recovery instructions. Prove /data can recover by running build, push, scan, pull and rollback first in demo.