Installare Harbor (registro di artefatti)
Questa guida spiega come installare e configurare Harbor su un server Ubuntu 24.04 LTS. Harbor è un registro di artefatti cloud-native di riferimento (progetto CNCF graduated): permette di memorizzare artefatti in formato OCI (Open Container Initiative). Puoi ospitare i tuoi build Docker (immagini di conteneurs), i tuoi chart Helm per Kubernetes, oltre a SBOM (Software Bill of Materials) e, nelle versioni recenti, artefatti IA/ML. Harbor integra Trivy per la scansione delle vulnerabilità, RBAC, OIDC/LDAP e la replica tra registri.
Il deployment descritto qui utilizza l’installer ufficiale (Docker Compose) su una VM o server dedicato, con HTTPS e certificati Let's Encrypt.
Ordina un server
Per ospitare la tua istanza Harbor, HostMyServers propone diverse opzioni adatte:
- VPS Performance - Ideale per un registro di test o volume ridotto
- VPS NVMe - Ottimo rapporto qualità/prezzo
- Server Dedicati Eco - Per molti progetti o immagini
- Server Dedicati Performance - Prestazioni massime
Prerequisiti
- Accesso SSH root o utente con sudo
- Sistema Ubuntu 24.04 LTS a 64 bit
- Docker (motore 20.10.10+) e Docker Compose (v2 o v1.18+)
- Un nome di dominio (es.
harbor.tuodominio.com) con record A che punta all'IP del server - Porte 80 (HTTP, per Certbot o redirect) e 443 (HTTPS) accessibili
Configurazione richiesta
| Componente | Minimo | Consigliato |
|---|---|---|
| RAM | 4 GB | 8 GB |
| CPU | 2 core | 4 core |
| Storage | 40 GB | 160 GB |
| Rete | 100 Mbps | 1 Gbps |
In produzione, configura sempre HTTPS con certificati validi (Let's Encrypt o PKI aziendale). Harbor depreca progressivamente HTTP.
Connessione al server
Connettiti via SSH al server:
ssh utente@indirizzo_ip_server
Aggiornamento del sistema
Aggiorna i pacchetti prima di iniziare:
sudo apt update
sudo apt upgrade -y
Installazione di Docker e Docker Compose
Harbor si appoggia a Docker e Docker Compose. Se non sono già installati:
sudo apt install -y ca-certificates curl
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
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:-$VERSION}") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Verifica:
docker --version
docker compose version
Ottenere i certificati TLS (Let's Encrypt)
Harbor deve essere configurato con un certificato e una chiave privata. Ottienili con Certbot prima di installare Harbor (la porta 80 deve essere libera):
sudo apt install -y certbot
sudo certbot certonly --standalone -d harbor.tuodominio.com -m tua-email@esempio.com --agree-tos --non-interactive
I file saranno in /etc/letsencrypt/live/harbor.tuodominio.com/: fullchain.pem (certificato) e privkey.pem (chiave privata). Annota questi percorsi per il passo successivo.
Certbot rinnova automaticamente i certificati. Dopo il rinnovo, riavvia i conteneurs Harbor per ricaricare i certificati: cd /opt/harbor && sudo docker compose down && sudo docker compose up -d.
Download ed estrazione di Harbor
Harbor fornisce un installer offline (include le immagini) o online (scarica le immagini al primo avvio). Utilizziamo l'installer offline per maggiore affidabilità.
Consulta le release Harbor su GitHub per l'ultima versione stabile (es. v2.14.2). Adatta URL e nome file se necessario:
cd /opt
sudo wget https://github.com/goharbor/harbor/releases/download/v2.14.2/harbor-offline-installer-v2.14.2.tgz
sudo tar xzvf harbor-offline-installer-v2.14.2.tgz
cd harbor
Configurazione di Harbor
Copia il template di configurazione e modificalo:
sudo cp harbor.yml.tmpl harbor.yml
sudo nano harbor.yml
Parametri essenziali da modificare (sostituisci con i tuoi valori):
# Nome host o dominio (mai localhost)
hostname: harbor.tuodominio.com
# HTTPS (obbligatorio in produzione)
https:
port: 443
certificate: /etc/letsencrypt/live/harbor.tuodominio.com/fullchain.pem
private_key: /etc/letsencrypt/live/harbor.tuodominio.com/privkey.pem
# Password admin (cambiare subito)
harbor_admin_password: TuaPasswordSicura
# Directory dati
data_volume: /data/harbor
# Scan vulnerabilità con Trivy (consigliato)
trivy:
ignore_unfixed: false
security_check: vuln,config,secret
skip_update: false
insecure: false
| Parametro | Descrizione |
|---|---|
hostname | Dominio o FQDN usato per accedere a Harbor (deve corrispondere al certificato) |
https.certificate / private_key | Percorsi verso certificato e chiave TLS |
harbor_admin_password | Password dell'account admin (cambiare al primo accesso) |
data_volume | Directory di storage dati Harbor |
trivy.* | Opzioni dello scanner Trivy (CVE, config, secrets) |
La password predefinita nel template è Harbor12345. Sostituiscila con una password robusta prima del primo avvio.
Avvio dell'installazione
Esegui lo script di installazione con l'opzione Trivy per abilitare la scansione delle vulnerabilità sulle immagini:
sudo ./install.sh --with-trivy
Lo script verifica i prerequisiti, prepara i file Docker Compose e avvia i conteneurs. Alla fine dovresti vedere:
✔ ----Harbor has been installed and started successfully.----
Firewall
Apri le porte HTTP e HTTPS se necessario:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload
Accesso a Harbor
- Apri un browser e vai a:
https://harbor.tuodominio.com - Accedi con le credenziali predefinite: admin / password impostata in
harbor_admin_password - Cambia subito la password admin: Amministrazione → Utenti → modifica account admin
- Crea un progetto (es.
mioprogetto) per caricare le tue immagini
Eseguire il push di un'immagine verso Harbor
Da una macchina con Docker installato che può raggiungere il tuo Harbor:
# Accesso al registro
docker login harbor.tuodominio.com
# Inserisci: admin e password
# Tagga un'immagine (sostituisci con il tuo progetto e immagine)
docker tag nginx:alpine harbor.tuodominio.com/mioprogetto/nginx:alpine
# Push dell'immagine
docker push harbor.tuodominio.com/mioprogetto/nginx:alpine
L'immagine compare nel progetto nell'interfaccia Harbor. Se Trivy è abilitato, una scansione può essere avviata automaticamente o manualmente per mostrare le vulnerabilità (CVE).
Harbor supporta anche la memorizzazione di chart Helm (formato OCI). Dopo aver configurato Helm con il tuo registro Harbor, puoi eseguire push e pull dei chart con helm push / helm pull dallo stesso progetto. Così un unico registro OCI può centralizzare le tue immagini Docker e i tuoi chart Helm per Kubernetes.
Gestione e arresto di Harbor
I conteneurs sono gestiti da Docker Compose in /opt/harbor:
cd /opt/harbor
# Elenca i conteneurs
sudo docker compose ps
# Arresta Harbor
sudo docker compose down
# Riavvia Harbor
sudo docker compose up -d
In caso di problemi
La pagina Harbor non si carica o errore HTTPS
- Verifica che hostname in
harbor.ymlcorrisponda esattamente al dominio usato nel browser e al nome comune del certificato. - Controlla i percorsi dei certificati:
sudo ls -la /etc/letsencrypt/live/harbor.tuodominio.com/ - Consulta i log:
cd /opt/harbor && sudo docker compose logs -f proxy
I conteneurs non si avviano
- Controlla i log:
cd /opt/harbor && sudo docker compose logs - Verifica lo spazio su disco:
df -h(Harbor e le immagini richiedono spazio) - Verifica che le porte 80 e 443 non siano usate da un altro servizio:
ss -tlnp | grep -E ':80|:443'
Docker login fallisce (x509, certificato)
- In sviluppo puoi aggiungere il registro come insecure in
/etc/docker/daemon.json(non consigliato in produzione). - In produzione assicurati che il certificato Let's Encrypt sia valido e che il client Docker si fidi del CA (spesso il caso con Let's Encrypt).