Come installare GitLab su Ubuntu 24.04 o 22.04 LTS

GitLab su Ubuntu LTS: quando ha senso installarlo e cosa serve davvero

GitLab non è un pacchetto “leggero” da mettere su una VM qualsiasi e dimenticare lì. Su Ubuntu 24.04 o 22.04 LTS funziona bene, ma solo se prima sistemi i prerequisiti che tendono a creare problemi in produzione: hostname corretto, DNS coerente, RAM sufficiente, storage veloce e una strategia minima per la posta in uscita. Se salti questi punti, l’installazione può anche completarsi, ma il risultato sarà un’istanza fragile, lenta o difficile da diagnosticare.

La scelta tra 22.04 e 24.04 non cambia il modello operativo: in entrambi i casi conviene usare il pacchetto ufficiale Omnibus, lasciare a GitLab la gestione dei suoi servizi interni e limitare le personalizzazioni iniziali a quelle strettamente necessarie. L’obiettivo non è “farlo partire”, ma ottenere una piattaforma stabile, con update ripetibili e rollback ragionevoli.

Prerequisiti che evitano il 90% dei problemi

Prima di installare, verifica questi punti. Sono noiosi, ma fanno la differenza tra una setup pulita e una giornata persa tra log e servizi in crash loop.

1. Hostname FQDN: GitLab vuole un nome stabile e risolvibile, ad esempio gitlab.example.com. Evita di usare un IP come URL principale, perché complica certificati, redirect e integrazioni.

2. DNS coerente: il record A/AAAA deve puntare all’IP corretto e la risoluzione inversa, se la usi, non deve contraddirlo. Per un controllo rapido:

dig +short gitlab.example.com
getent hosts gitlab.example.com
hostname -f

3. RAM: sotto i 4 GB il sistema parte, ma la user experience peggiora in fretta. Per un’istanza piccola ma usabile, considera almeno 4 GB; meglio 8 GB se prevedi repository numerosi, CI, container registry o traffico consistente.

4. Storage: usa disco SSD/NVMe e tieni margine. GitLab scrive su repository, upload, artefatti, log e database. Un filesystem quasi pieno è una delle cause più comuni di degrado e errori 5xx.

5. Posta in uscita: senza SMTP o relay affidabile, reset password, notifiche e inviti diventano un problema operativo. Se non hai ancora il relay, puoi installare comunque, ma devi sapere che alcune funzioni resteranno limitate.

6. Porta 80 e 443 libere: se hai già Apache, Nginx o un altro reverse proxy sul nodo, devi decidere chi termina TLS. Per una installazione standard Omnibus, GitLab può gestire direttamente HTTP/HTTPS; se vuoi metterlo dietro proxy, va configurato in modo esplicito.

Installazione del pacchetto ufficiale su Ubuntu 24.04 o 22.04

La via più pulita è il repository ufficiale GitLab. Evita pacchetti presi a caso o script “one click” non mantenuti: ti fanno perdere il controllo sugli aggiornamenti e sul debug.

1. Aggiorna il sistema e installa i prerequisiti base.

sudo apt update
sudo apt -y install curl openssh-server ca-certificates tzdata perl

Se usi UFW, apri solo ciò che serve davvero:

sudo ufw allow OpenSSH
sudo ufw allow http
sudo ufw allow https
sudo ufw status verbose

2. Aggiungi il repository GitLab. Per Ubuntu LTS moderne, il pacchetto omnibus è il riferimento pratico. Usa il canale stabile e non improvvisare con mirror non ufficiali.

curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

Qui ho usato gitlab-ee perché il repository ufficiale copre il pacchetto enterprise; in ambienti dove serve la community edition, il flusso è simile ma va verificata la disponibilità del pacchetto corretto nel tuo repository. Se il tuo obiettivo è un’installazione standard senza feature enterprise, controlla prima quale edizione vuoi davvero mantenere nel tempo, così non ti ritrovi a migrare dopo pochi mesi.

3. Installa GitLab specificando l’URL pubblico definitivo. Questo è il punto più importante della procedura.

sudo EXTERNAL_URL="https://gitlab.example.com" apt -y install gitlab-ee

Se preferisci la versione community, sostituisci il pacchetto con quello disponibile nel repository che hai scelto. L’URL esterno deve essere quello che gli utenti useranno davvero, non un hostname temporaneo.

4. Verifica che i servizi Omnibus siano su.

sudo gitlab-ctl status

In una installazione sana dovresti vedere i componenti principali attivi: nginx, puma, sidekiq, postgresql, redis e gli altri servizi interni. Se uno o più servizi sono down, non forzare subito il riavvio a ripetizione: prima leggi i log.

I log più utili sono in /var/log/gitlab/, con sotto-cartelle dedicate ai singoli componenti. Per iniziare, guarda i messaggi recenti di configurazione e startup:

sudo gitlab-ctl tail
sudo tail -n 100 /var/log/gitlab/gitlab-rails/production.log
sudo tail -n 100 /var/log/gitlab/nginx/gitlab_error.log

Configurazione iniziale: file `gitlab.rb` e punti da non sbagliare

Il file principale è /etc/gitlab/gitlab.rb. Ogni modifica importante passa da lì, poi si applica con gitlab-ctl reconfigure. Il vantaggio è chiaro: hai una configurazione dichiarativa, tracciabile e relativamente facile da ripristinare.

Prima di toccarlo, fai un backup semplice del file corrente:

sudo cp -a /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak.$(date +%F-%H%M%S)

Le prime direttive da considerare sono queste:

external_url 'https://gitlab.example.com'

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']

nginx['redirect_http_to_https'] = true

Se usi un certificato già emesso da un altro sistema, disattiva Let’s Encrypt e punta ai file del certificato manuale. In quel caso le variabili cambiano e devi mantenere il controllo su rinnovo, permessi e path.

Per esempio, con certificato esterno puoi avere qualcosa del genere:

nginx['ssl_certificate'] = "/etc/ssl/certs/gitlab.example.com.crt"
nginx['ssl_certificate_key'] = "/etc/ssl/private/gitlab.example.com.key"

Non lasciare chiavi private in percorsi leggibili da utenti non privilegiati. Controlla i permessi e, se necessario, redigi i contenuti sensibili nei documenti condivisi. La configurazione deve essere sicura anche quando passa di mano tra operatori diversi.

Applicare la configurazione e leggere il risultato senza andare a tentoni

Una volta editato gitlab.rb, applica la configurazione:

sudo gitlab-ctl reconfigure

Il comando può richiedere alcuni minuti. Se fallisce, la causa quasi sempre è leggibile nei log di configurazione o nei componenti coinvolti: certificato non trovato, porta occupata, DNS non risolvibile, permessi errati, database non avviato o memoria insufficiente.

Due controlli rapidi dopo il reconfigure:

sudo gitlab-ctl status
curl -Ik https://gitlab.example.com

Nel primo caso vuoi vedere i servizi in stato run. Nel secondo vuoi ottenere un HTTP/2 200, oppure almeno una risposta coerente con il redirect iniziale se stai ancora rifinendo il TLS. Se ricevi timeout o 502/503, il problema è quasi sempre a livello di origin, non nel browser.

Se invece la pagina risponde ma l’interfaccia mostra errori applicativi, guarda i log Rails e Sidekiq. GitLab separa bene i componenti, quindi un guasto può essere circoscritto a un solo servizio senza buttare giù tutto il resto.

SMTP, notifiche e perché conviene sistemarli subito

Molti installano GitLab, poi si accorgono dopo che email di invito, reset password e notifiche pipeline non escono. È un errore operativo classico. Se l’istanza serve più di due utenti, la posta va definita subito.

Un esempio minimale di configurazione SMTP in gitlab.rb:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.example.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "gitlab@example.com"
gitlab_rails['smtp_password'] = "REDACTED"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

La password non va mai lasciata in chiaro in documenti condivisi. Se devi passare questa configurazione a un altro amministratore, sostituisci il segreto con un placeholder e conserva il valore reale nel vault o nel sistema di secret management che usi in azienda.

Dopo la modifica, applica di nuovo:

sudo gitlab-ctl reconfigure
sudo gitlab-rake gitlab:check

Se la posta non funziona, il test da fare non è “vediamo se arriva un’email a caso”, ma verificare connessione, autenticazione e log applicativo. In caso di errori TLS o autenticazione, il relay di solito parla chiaro nei suoi log.

Reverse proxy esterno: quando conviene e come non rompere GitLab

Se hai già uno stack con Nginx, Apache o un bilanciatore davanti, puoi mettere GitLab dietro un reverse proxy esterno. Ha senso quando vuoi centralizzare TLS, WAF, rate limiting o terminazione HTTPS su un layer già standardizzato.

La regola è semplice: o lasci a GitLab la terminazione HTTPS, oppure la sposti fuori. Mischiare i due modelli senza disciplina produce problemi di redirect, header sbagliati e cookie non coerenti.

Se il proxy esterno termina TLS, in GitLab devi configurare correttamente l’URL pubblico e, in alcuni casi, l’header del proxy. Il punto critico è preservare X-Forwarded-Proto, X-Forwarded-For e l’host originale. Un proxy configurato male fa sembrare GitLab instabile anche quando non lo è.

Esempio concettuale per Nginx esterno:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
}

Questo snippet è volutamente minimale: nella pratica dovrai adattarlo alla tua architettura e verificare che GitLab ascolti sulla porta prevista. Il controllo finale è sempre lo stesso: accesso web, login, clone via HTTPS e, se usi SSH, handshake sulla porta 22 o su quella custom definita.

SSH per repository e accesso: il dettaglio che spesso si dimentica

GitLab usa SSH in modo intensivo per il push e il pull dei repository. Se la porta 22 è occupata o se il server è dietro NAT o firewall restrittivo, devi pianificare il mapping prima che gli utenti inizino a lavorare.

Verifica che il servizio SSH del sistema sia attivo e che GitLab esponga la porta attesa. Da client:

ssh -T git@gitlab.example.com

Se hai configurato una porta diversa, GitLab la mostra nella UI del progetto o del profilo utente. È un dettaglio banale, ma se sbagli qui gli sviluppatori iniziano a fare troubleshooting sul lato sbagliato, perdendo tempo su chiavi SSH perfettamente valide.

Backup, upgrade e rollback: la parte che ti salva davvero

Una installazione GitLab senza piano di backup è un rischio, non un servizio. Prima di pensare agli upgrade, stabilisci almeno tre cose: cosa salvi, dove lo salvi e come verifichi il ripristino.

Per gli snapshot operativi, il minimo sindacale è includere configurazione, database e dati applicativi. GitLab offre strumenti propri per il backup, ma il dettaglio preciso dipende dalla dimensione dell’istanza e dal posizionamento dello storage. Non basta copiare la directory a mano e sperare che basti.

Per un controllo base dei backup disponibili e della salute generale:

sudo gitlab-backup create
sudo gitlab-rake gitlab:check
sudo du -sh /var/opt/gitlab/backups

Prima di fare upgrade importanti, leggi la nota di release della versione target e controlla la compatibilità con Ubuntu 24.04 o 22.04, soprattutto se stai passando tra major version di GitLab. Un upgrade non testato in staging è il modo più rapido per trasformare manutenzione in incidente.

Rollback pratico: tieni sempre a portata il backup di /etc/gitlab/gitlab.rb, la versione del pacchetto installato e uno snapshot della VM, se l’infrastruttura lo consente. Se qualcosa si rompe dopo un cambio di configurazione, il primo tentativo deve essere tornare al file precedente e rieseguire gitlab-ctl reconfigure, non smontare metà stack a mano.

Checklist finale prima di mettere l’istanza in mano agli utenti

Se vuoi evitare sorprese, fai questa verifica minima prima del go-live:

1. Il nome pubblico risolve correttamente: dig +short gitlab.example.com.
2. Il servizio risponde in HTTPS: curl -Ik https://gitlab.example.com restituisce un codice coerente.
3. I servizi interni sono attivi: sudo gitlab-ctl status non mostra componenti down.
4. La posta esce davvero: test SMTP e osservazione del log di invio.
5. Il backup parte e produce un file o una directory di dimensione plausibile.
6. Le credenziali admin iniziali vengono cambiate subito e l’accesso root non resta in uso quotidiano.

Se uno di questi punti fallisce, non è un dettaglio: è un problema da correggere prima che l’istanza diventi dipendente da utenti reali. GitLab è robusto, ma non compensa una base infrastrutturale incoerente.

Assunzione operativa: Ubuntu 22.04 o 24.04 LTS con privilegi sudo, dominio pubblico già delegato e accesso a un relay SMTP o a un certificato TLS valido.

Se vuoi ridurre al minimo la manutenzione, la regola pratica è semplice: installazione ufficiale, configurazione esplicita, backup verificato e niente scorciatoie sui certificati o sulla posta. È noioso, ma è il modo giusto per avere un GitLab che resta in piedi quando serve davvero.