Come installare GitLab su un server dedicato

GitLab è una piattaforma per repository Git, code review, issue tracking e CI/CD che puoi eseguire sul tuo server. Un'istanza self-hosted mantiene il tuo codice sorgente sotto il tuo controllo, e la sua capacità dipende solo dalle risorse del server e dalle funzionalità di GitLab che utilizzi.

Un server dedicato è adatto a GitLab. L'archiviazione dei repository sfrutta intensamente i dischi, e il database e i servizi in background richiedono una quantità costante di RAM. Su hardware dedicato queste risorse non sono condivise con nessun altro, quindi GitLab resta reattivo durante grandi push ed esecuzioni di CI.

Perché eseguire il tuo GitLab

GitLab.com è comodo per iniziare, ma con la crescita di un team un'istanza self-hosted diventa spesso la scelta migliore:

• Il codice resta sul tuo server. Codice sorgente, issue e segreti CI/CD sono archiviati su hardware che controlli, nella sede del data center che scegli. Questo conta per i progetti con requisiti di NDA o di residenza dei dati.
• Nessun limite di piano su utenti, storage e minuti CI/CD. Il livello gratuito di GitLab.com li limita, mentre sul tuo server i limiti dipendono solo dalle sue risorse.
• I tuoi runner CI/CD. Le build vengono eseguite sui tuoi server senza pagare minuti di calcolo e possono raggiungere servizi interni chiusi a internet.
• Pieno controllo su aggiornamenti e impostazioni. Decidi tu quando aggiornare, quali integrazioni attivare e come fare il backup dei dati.

Se usi già GitLab.com, installa prima la tua istanza e poi sposta gruppi e progetti.

Questa guida mostra come installare GitLab dal pacchetto ufficiale su Ubuntu o Debian, ottenere un certificato Let's Encrypt gratuito e preparare l'istanza per il tuo team.

Cosa serve prima dell'installazione

Un server dedicato con almeno 8 vCPU (thread della CPU) e 16 GB di RAM. Un processore a 4 core con Hyper-Threading o SMT offre già 8 thread. GitLab può partire con 8 GB di RAM, ma ne usa quasi tutta ed è lento sotto carico. Usa dischi SSD o NVMe con almeno 40 GB liberi per il sistema e GitLab, più spazio sufficiente per tutti i repository e i backup.

Ubuntu 26.04 LTS, Ubuntu 24.04 LTS o Debian 13 installato sul server. I comandi di questa guida sono uguali per tutti e tre i sistemi; dove Debian differisce, è indicato.

Un dominio o sottodominio per GitLab, ad esempio gitlab.example.com.

Un record DNS A che punti questo dominio all'indirizzo IPv4 pubblico del server.

Accesso root o un utente con diritti sudo. I comandi di questa guida sono eseguiti come root; se usi un utente con sudo, aggiungi sudo davanti. Nel comando che aggiunge il repository GitLab, metti sudo prima di bash: curl ... | sudo bash.

Porte 22 (SSH), 80 (HTTP) e 443 (HTTPS) aperte a internet. La porta 80 è necessaria anche se prevedi di usare solo HTTPS, perché Let's Encrypt verifica il dominio via HTTP.

Connettersi al server

Connettiti al server via SSH dal tuo computer:

ssh [email protected]

Controlla la versione del sistema operativo:

cat /etc/os-release

Esempio di output:

PRETTY_NAME="Ubuntu 26.04 LTS"
NAME="Ubuntu"
VERSION_ID="26.04"
...

L'output deve mostrare Ubuntu 26.04, Ubuntu 24.04 o Debian 13. Poi controlla il numero di core della CPU, la quantità di RAM e lo spazio libero su disco:

nproc
free -h
df -h /

Assicurati che il dominio punti già al server. Esegui questo comando sul tuo computer locale (funziona su Windows, macOS e Linux):

nslookup gitlab.example.com

Il record A deve restituire l'indirizzo IPv4 pubblico del server. Se usi anche un record AAAA, assicurati che il server sia raggiungibile via IPv6. Se gli indirizzi non coincidono, correggi i record DNS e attendi che la modifica diventi effettiva. Non proseguire finché il dominio non viene risolto correttamente, perché GitLab richiede il certificato Let's Encrypt durante la configurazione iniziale.

Aggiornare il server e installare le dipendenze

Aggiorna gli elenchi dei pacchetti e i pacchetti installati:

apt update && apt upgrade -y

Imposta l'hostname del server sul dominio di GitLab. GitLab non lo richiede, ma così il nome del sistema resta coerente con l'indirizzo di GitLab nei log e nelle email in uscita:

hostnamectl set-hostname gitlab.example.com

Installa i pacchetti necessari a GitLab:

apt install -y curl openssh-server ca-certificates perl tzdata locales

GitLab richiede anche una locale UTF-8: senza di essa, il database PostgreSQL incluso può non inizializzarsi durante l'installazione. Abilita en_US.UTF-8 nell'elenco delle locali e generala (su Ubuntu 26.04 è già abilitata e il primo comando non cambia nulla):

sed -i 's/^# *en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen
locale-gen

Configurare il firewall

Questa guida usa il firewall UFW. È incluso in Ubuntu ma disattivato per impostazione predefinita; su Debian, installalo prima:

apt install -y ufw

Se UFW è già attivo sul tuo server, controlla prima le regole attuali con ufw status. Consenti SSH, HTTP e HTTPS e solo dopo attiva il firewall, così la tua sessione SSH non viene interrotta:

ufw allow ssh
ufw allow http
ufw allow https
ufw enable

Rispondi y quando richiesto di confermare. Controlla le regole:

ufw status

Esempio di output:

Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
22/tcp (v6)                ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)

Aggiungere il repository GitLab

GitLab è distribuito in due edizioni:

• GitLab Enterprise Edition (gitlab-ee). Include tutte le funzionalità gratuite e permette di attivare in seguito quelle a pagamento senza reinstallare.
• GitLab Community Edition (gitlab-ce). Una build completamente open source con le funzionalità gratuite di GitLab.

Questa guida usa gitlab-ee. Se preferisci la Community Edition, sostituisci gitlab-ee con gitlab-ce in tutti i comandi.

Aggiungi il repository ufficiale di GitLab:

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

Lo script aggiunge il repository e la sua chiave di firma e aggiorna l'elenco dei pacchetti.

Installare GitLab

Installa il pacchetto e passa l'indirizzo della tua istanza in EXTERNAL_URL. Usa https:// nell'indirizzo: in questo caso GitLab richiede un certificato Let's Encrypt e configura automaticamente il reindirizzamento da HTTP a HTTPS.

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

Durante l'installazione, GitLab estrae i suoi componenti (il web server, il database PostgreSQL, Redis, lo storage Git e i servizi in background), scrive la configurazione in /etc/gitlab/gitlab.rb, richiede il certificato e avvia tutti i servizi. Ci vogliono da 5 a 10 minuti. Al termine, l'output finisce con il messaggio «Thank you for installing GitLab!».

Esempio di output:

Thank you for installing GitLab!
GitLab should be available at https://gitlab.example.com

GitLab genera una password casuale per l'account root e la salva in un file. Visualizzala:

cat /etc/gitlab/initial_root_password

Copia la password. Il file viene eliminato automaticamente 24 ore dopo l'installazione, quindi accedi e imposta la tua password prima di allora.

Aprire GitLab e verificare HTTPS

Apri https://gitlab.example.com nel browser. La pagina deve aprirsi senza avvisi di sicurezza e il browser deve mostrare un certificato valido emesso da Let's Encrypt.

Accedi con il nome utente root e la password da initial_root_password.

Cambia subito la password. Seleziona il tuo avatar, poi Edit profile. Nel menu a sinistra espandi Access, seleziona Password and authentication, poi Change password. Inserisci la password attuale e una nuova e seleziona Save password. GitLab rifiuta le password deboli, comprese quelle che contengono la parola «gitlab» o il tuo nome utente.

Se la pagina non si apre via HTTPS, con ogni probabilità il certificato non è stato emesso. In questo caso l'output dell'installazione contiene un errore di Let's Encrypt. Verifica che il dominio venga risolto nell'indirizzo IP del server, che la porta 80 sia aperta e che non ci sia un record AAAA senza IPv6 funzionante. Dopo aver risolto la causa, richiedi di nuovo il certificato:

gitlab-ctl reconfigure

Let's Encrypt limita il numero di tentativi falliti all'ora, quindi risolvi la causa prima di riprovare.

Configurazione di base di GitLab

Disattivare la registrazione pubblica. Se l'istanza è solo per il tuo team, disattiva la creazione di account dalla pagina di registrazione. Per impostazione predefinita, chiunque apra la tua pagina GitLab può registrarsi, e il nuovo account resta in attesa dell'approvazione di un amministratore. Il modo più rapido è il pulsante Deactivate nel banner della home page di GitLab. In alternativa, seleziona Admin nell'angolo in alto a destra, vai a Settings > General ed espandi New user account restrictions. Deseleziona la casella Allow new user accounts e seleziona Save changes. I nuovi account saranno creati solo dagli amministratori.

Creare account utente. Vai a Admin > Instance overview > Users e seleziona New user, compila nome, nome utente e indirizzo email e seleziona Create user. Usa un account personale con diritti di amministratore per il lavoro quotidiano e l'account root solo quando necessario.

Creare un gruppo. I gruppi riuniscono progetti e membri del team. Seleziona Create new (l'icona del più) nella barra superiore, poi New group > Create group, inserisci un nome e seleziona Create group. Aggiungi i colleghi al gruppo in Manage > Members.

Aggiungere una chiave SSH. Per lavorare con i repository via SSH, ogni utente aggiunge la propria chiave pubblica in Edit profile > Access > SSH keys: seleziona Add new key, incolla la chiave e seleziona Add key.

Verificare l'installazione

Verifica che tutti i servizi GitLab siano in esecuzione:

gitlab-ctl status

Esempio di output:

run: gitaly: (pid 2981) 512s; run: log: (pid 2975) 512s
run: gitlab-workhorse: (pid 3412) 498s; run: log: (pid 3401) 498s
run: nginx: (pid 3530) 495s; run: log: (pid 3522) 495s
run: postgresql: (pid 3105) 507s; run: log: (pid 3098) 507s
run: puma: (pid 3288) 501s; run: log: (pid 3280) 501s
run: redis: (pid 2950) 514s; run: log: (pid 2944) 514s
run: sidekiq: (pid 3350) 499s; run: log: (pid 3342) 499s
...

Ogni riga deve iniziare con run:.

Esegui il controllo integrato di configurazione e servizi:

gitlab-rake gitlab:check SANITIZE=true

Crea un repository di prova. Nell'interfaccia web, seleziona Create new > New project/repository > Create blank project, inserisci il nome test, seleziona il tuo gruppo e lascia selezionata l'opzione Initialize repository with a README. Seleziona Create project.

Verifica l'accesso via SSH dal tuo computer:

ssh -T [email protected]

Esempio di output:

Welcome to GitLab, @username!

Una configurazione funzionante risponde con un messaggio di benvenuto contenente il tuo nome utente. Poi clona il repository di prova:

git clone [email protected]:group/test.git

Sostituisci group con il percorso del tuo gruppo. Se il repository viene clonato e contiene README.md, GitLab è installato e funziona.

Cosa configurare dopo

Backup. Il comando gitlab-backup create crea un backup dell'applicazione con il database di GitLab, i repository e altri dati dell'applicazione in /var/opt/gitlab/backups. I file di configurazione /etc/gitlab/gitlab.rb e /etc/gitlab/gitlab-secrets.json non sono inclusi e vanno salvati separatamente, ad esempio con gitlab-ctl backup-etc. Senza gitlab-secrets.json, un'istanza ripristinata non può decifrare le impostazioni 2FA e le variabili CI/CD. Esegui regolarmente i backup dell'applicazione e della configurazione e copiali su uno storage esterno al server GitLab, ad esempio su INTROSERV Cloud Storage: vedi Collegare INTROSERV Cloud Storage al server.

Posta in uscita. Configura un server SMTP in /etc/gitlab/gitlab.rb affinché GitLab possa inviare notifiche, reimpostazioni di password e conferme di account. Vedi Impostazioni SMTP nella documentazione di GitLab.

GitLab Runner. Runner esegue le pipeline CI/CD. Le build usano molta CPU e RAM, quindi è meglio installare Runner su un VPS o server dedicato separato anziché sul server GitLab stesso.

Aggiornamenti. GitLab rilascia una nuova versione ogni mese e correzioni di sicurezza più spesso. Prima di aggiornare saltando più versioni, controlla il percorso di aggiornamento ufficiale: GitLab deve passare per alcune versioni intermedie. Crea un backup, poi aggiorna con apt update && apt install -y gitlab-ee.

Monitoraggio. GitLab include Prometheus ed esporta le proprie metriche. Lo stato dell'istanza si controlla in Admin > Monitoring > Health check, e gli endpoint elencati lì possono essere collegati al tuo sistema di monitoraggio esterno.

Per scegliere un server per la tua istanza GitLab, vedi la pagina Server dedicati.