IT

Applicazioni

Installare Coolify e distribuire una prima applicazione

Installa Coolify su Debian o Ubuntu senza esporre la sua dashboard, metti in sicurezza l'istanza, distribuisci un'applicazione in HTTPS, poi gestisci aggiornamenti e backup.

13 min di lettura, aggiornato il 18 novembre 2026

In questa pagina

I tuoi valori

Inseriscili una volta: i comandi della guida si aggiornano.

Coolify è una piattaforma self-hosted che distribuisce le tue applicazioni, i tuoi database e i tuoi servizi sui tuoi server. Si basa su Docker e su un reverse proxy che gestisce i domini e i certificati HTTPS.

Al termine di questa guida, la dashboard risponde su https://coolify.tuo-dominio.com, le sue porte dirette non sono esposte su Internet, l'account amministratore è protetto e una prima applicazione funziona su https://app.tuo-dominio.com.

Ordina un Server

Questa guida si applica ai server che amministri tu stesso:

Prerequisiti

  • Preferibilmente un server dedicato a Coolify, con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
  • Almeno 2 core, 2 GB di RAM e 10 GB di spazio libero, da aumentare in base alle tue applicazioni e alle tue compilazioni
  • Un accesso SSH con root o con un utente che dispone di sudo
  • Docker Engine 24 o successivo, installato con la guida Installare Docker Engine e Docker Compose. In alternativa, il programma di installazione di Coolify prova a installarlo da solo, ma rifiuta la versione snap
  • Un nome di dominio di cui gestisci la zona DNS
  • Nessun servizio che occupi le porte 80 e 443, come Nginx, Apache o Caddy

Questa guida usa la versione 4.7.5, la versione stabile al momento della stesura. Controlla l'ultima versione nel file delle versioni di Coolify.

Porte utilizzate

Porta Ruolo Esposizione in questa guida
22/tcp SSH, compresa la connessione di Coolify al server Aperta
80/tcp HTTP e validazione dei certificati Pubblica, tramite il proxy
443/tcp HTTPS Pubblica, tramite il proxy
443/udp HTTP/3 Pubblica, tramite il proxy
8000/tcp Accesso diretto alla dashboard Solo 127.0.0.1
6001/tcp Aggiornamenti in tempo reale Solo 127.0.0.1
6002/tcp Terminale web Solo 127.0.0.1
8080/tcp Porta pubblicata dalla configurazione predefinita di Traefik Rimossa al passo 7

Se usi UFW, mantieni aperto SSH con sudo ufw allow 22/tcp, senza una regola limit: può interrompere le connessioni ripetute di Coolify.

Passo 1: preparare il DNS

Crea due record A verso IP_DEL_TUO_SERVER:

Nome Utilizzo
coolify.tuo-dominio.com Dashboard
app.tuo-dominio.com Prima applicazione

Se il tuo dominio è gestito presso HostMyServers, segui la guida Creare un record A. Verifica poi:

Terminale
dig +short A coolify.tuo-dominio.com
dig +short A app.tuo-dominio.com
dig +short AAAA coolify.tuo-dominio.com

I primi due comandi devono restituire l'indirizzo del server. Se l'ultimo restituisce un indirizzo IPv6, anche questo deve puntare a questo server, altrimenti la creazione del certificato può non riuscire.

Passo 2: autorizzare la connessione SSH di Coolify

Coolify si connette al server via SSH con l'account root e una chiave dedicata. Controlla l'impostazione attiva:

Terminale
sudo sshd -T | grep -i '^permitrootlogin'

I valori prohibit-password, without-password e yes vanno bene. Se ottieni no, autorizza root solo tramite chiave:

Terminale
echo 'PermitRootLogin prohibit-password' | sudo tee /etc/ssh/sshd_config.d/00-coolify.conf
sudo sshd -t
sudo systemctl reload ssh

Mantieni aperta la tua sessione e prova una nuova connessione prima di chiuderla.

Se hai seguito Proteggi il tuo server, SSH è in ascolto sulla porta 2222. Sostituisci 22 con 2222 nelle regole UFW di questa guida, poi indica questa porta in Servers > localhost > General dopo aver installato Coolify.

Passo 3: riservare le porte all'indirizzo locale

Senza precauzioni, la dashboard verrebbe pubblicata in HTTP sulla porta 8000 e il primo visitatore potrebbe crearvi l'account amministratore. Crea quindi il file di personalizzazione prima dell'installazione. Coolify lo conserva durante gli aggiornamenti.

Passa a root:

Terminale
sudo -i
mkdir -p /data/coolify/source
nano /data/coolify/source/docker-compose.custom.yml

Incolla questo contenuto:

YAML
services:
  coolify:
    ports: !override
      - "127.0.0.1:${APP_PORT:-8000}:8080"
      - "127.0.0.1:${SOKETI_PORT:-6001}:6001"
      - "127.0.0.1:6002:6002"

Passo 4: installare Coolify

Sempre come root, scarica lo script ufficiale, esaminalo, poi avvialo con la versione scelta:

Terminale
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
less /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5

Lo script installa i pacchetti necessari, adatta la configurazione di Docker, crea /data/coolify, genera la chiave SSH di Coolify e avvia i suoi container. Può riavviare Docker: è un motivo in più per partire da un server nuovo.

Al termine, mostra un indirizzo http://...:8000. Non risponderà da Internet, ed è il risultato voluto. Verifica le porte:

Terminale
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

La riga coolify deve indicare healthy e porte che iniziano con 127.0.0.1:.

Passo 5: aprire il tunnel SSH

In un terminale sul tuo computer, apri un tunnel verso le tre porte:

Terminale
ssh -N -L 8000:127.0.0.1:8000 -L 6001:127.0.0.1:6001 -L 6002:127.0.0.1:6002 TUO_USER@IP_DEL_TUO_SERVER

Il comando resta attivo senza mostrare nulla. Lascia aperto questo terminale durante la configurazione. Il traffico tra il tuo computer e il server è cifrato da SSH.

Passo 6: creare l'account amministratore

Apri http://localhost:8000 e crea subito l'account, con una password lunga e unica. Coolify accetta il primo account solo per 10 minuti dopo l'avvio.

Segui poi la procedura guidata e scegli di usare questo server (localhost). In Servers > localhost, la connessione deve risultare convalidata. In caso contrario, consulta la sezione sulla risoluzione dei problemi.

Copia subito la chiave di cifratura dell'istanza in un gestore di password:

Terminale
grep '^APP_KEY=' /data/coolify/source/.env

Passo 7: avviare il proxy

Apri Servers > localhost > Proxy. Traefik è il proxy predefinito.

In Configuration, rimuovi la riga seguente, inutile per questa configurazione, poi salva:

YAML
      - '8080:8080'

Clicca poi su Start Proxy, oppure riavvia il proxy se è già in esecuzione. Sul server, verifica che sia in ascolto:

Terminale
docker ps --filter name=coolify-proxy --format '{{.Names}} {{.Status}} {{.Ports}}'

Le porte 80 e 443 devono comparire su 0.0.0.0, e 8080 non deve più figurare nell'elenco.

Passo 8: pubblicare la dashboard in HTTPS

Apri Settings > General. In URL, inserisci:

Testo
https://coolify.tuo-dominio.com

Lascia attivo Redirect HTTP to HTTPS, poi clicca su Save changes. Dopo qualche istante, apri https://coolify.tuo-dominio.com e controlla il certificato:

Terminale
curl -I https://coolify.tuo-dominio.com

Verifica che i dati si aggiornino in tempo reale e, se lo usi, che il terminale web funzioni. Puoi poi chiudere il tunnel con Ctrl+C. Resta il tuo accesso di emergenza se il dominio non risponde più.

Passo 9: mettere in sicurezza l'istanza

Impostazione Posizione Valore consigliato
Registrazioni Settings > Advanced > Registration Registration disabled
Autenticazione a due fattori Profile > Two-factor Authentication > Configure 2FA Attivata, con i codici di riserva conservati a parte
API Settings > Advanced > API access Disabled se non la usi
Server MCP Settings > Advanced Disattivato, salvo esigenze specifiche
Indirizzi autorizzati Settings > Advanced > Allowed IPs I tuoi indirizzi, se attivi l'API
Team Team Ruolo minimo per ogni membro

Da un'altra macchina, senza tunnel, controlla ciò che è raggiungibile:

Terminale
nmap -Pn -p 22,80,443,6001,6002,8000,8080 IP_DEL_TUO_SERVER

Solo 22, 80 e 443 devono risultare open.

Passo 10: distribuire una prima applicazione

Questo esempio usa un'immagine pronta all'uso: non richiede né un repository Git né una compilazione.

  1. Apri Projects, crea un progetto chiamato demo, poi aprilo.
  2. Clicca su + New (o Create New Resource), poi scegli Docker Image.
  3. Inserisci l'immagine nginx:1.30-alpine e continua.
  4. In Ports Exposes, indica 80.
  5. In Domains, clicca su Add domain, scegli https e inserisci app.tuo-dominio.com.
  6. Clicca su Deploy e segui i log della distribuzione.

Verifica poi il risultato:

Terminale
curl -I https://app.tuo-dominio.com

La risposta deve essere un codice 200 e il browser deve mostrare la pagina iniziale di Nginx con un certificato valido.

Distribuire da un repository Git pubblico

Nel progetto, clicca su + New, scegli Public Repository, incolla l'indirizzo HTTPS del repository, poi clicca su Check repository. Scegli poi il Build pack, la porta dell'applicazione e il suo dominio, quindi avvia Deploy.

Per impostazione predefinita, la compilazione viene eseguita su questo server e può consumare molta CPU e memoria.

Aggiornare Coolify

Un aggiornamento di Coolify non modifica né le tue applicazioni, né il sistema, né Docker. Prima di avviarlo, leggi le note di rilascio, attendi la fine delle distribuzioni in corso ed esegui un backup.

Dalla dashboard

Apri Settings > Updates, mantieni il canale Stable, poi clicca su Upgrade now quando è disponibile una versione. L'impostazione Automatic updates determina se Coolify installa da solo le nuove versioni. Disattivala se preferisci mantenere il controllo sulle tempistiche.

Dal terminale

Esegui come root, indicando la versione desiderata senza v:

Terminale
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | bash -s 4.7.5

Non usare install.sh per un aggiornamento ordinario: reimposta i proprietari e i permessi in /data/coolify. Il file docker-compose.custom.yml continua a essere applicato. Controlla poi la versione mostrata nella dashboard e, se necessario, i log /data/coolify/source/upgrade-*.log.

Backup e ripristino

Conserva questi elementi fuori dal server:

Elemento Posizione Perché
Database di Coolify Backup .dmp Progetti, impostazioni e segreti cifrati
Chiave APP_KEY e file .env /data/coolify/source/.env Senza questa chiave, i segreti ripristinati sono illeggibili
Chiavi SSH /data/coolify/ssh/keys/ Connessione ai server gestiti
Personalizzazione delle porte /data/coolify/source/docker-compose.custom.yml Mantiene la protezione delle porte
Dati delle applicazioni Volumi e database Non inclusi nel backup di Coolify

Dalla dashboard

Apri Settings > Backup, clicca su Configure backup, poi su Back up now. Controlla il risultato in Executions e usa Download per recuperare una copia. Puoi anche aggiungere uno storage S3. Lascia attivo Backup before update per ottenere un backup prima di ogni aggiornamento avviato dall'interfaccia.

Dal terminale

Come root:

Terminale
mkdir -p /data/backups
docker exec coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify > "/data/backups/coolify-db-$(date +%F).dmp"
test -s "/data/backups/coolify-db-$(date +%F).dmp" && echo OK
tar czf "/data/backups/coolify-files-$(date +%F).tar.gz" -C /data/coolify source/.env source/docker-compose.custom.yml ssh/keys
chmod 600 /data/backups/*

Questi file contengono segreti: copiali in una posizione cifrata.

Ripristinare sullo stesso server

Sostituisci AAAA-MM-GG con la data del backup. Il database attuale verrà sostituito. Verifica prima che APP_KEY in /data/coolify/source/.env corrisponda alla chiave salvata, poi esegui come root:

Terminale
docker stop coolify coolify-redis
docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < /data/backups/coolify-db-AAAA-MM-GG.dmp
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5

Indica la versione installata al momento del backup. Su un nuovo server, segui la procedura ufficiale di ripristino, che recupera anche le chiavi SSH.

In caso di problemi

Setup window closed

Il limite di 10 minuti è stato superato. Riavvia Coolify, poi ricarica la pagina:

Terminale
docker restart coolify

L'indirizzo con :8000 non risponde

È normale da Internet. Passa dal tunnel del passo 5 e apri http://localhost:8000. Se il tunnel non funziona, controlla lo stato dei container con docker ps.

I dati non si aggiornano nella dashboard

La connessione in tempo reale non riesce. Con il tunnel, verifica che includa le porte 6001 e 6002. Con il dominio, verifica che il proxy sia in esecuzione e che nessun altro proxy blocchi i WebSocket.

Permission denied (publickey) durante la convalida del server

La chiave di Coolify manca per root, oppure root non può connettersi. Verifica il passo 2. Il programma di installazione non conserva la chiave pubblica sul disco: ricalcolala come root a partire dalla chiave privata, poi aggiungila:

Terminale
ssh-keygen -y -f /data/coolify/ssh/keys/id.root@host.docker.internal | sed 's/$/ coolify/' >> /root/.ssh/authorized_keys

Se questo file non esiste, elenca la cartella con ls /data/coolify/ssh/keys/ e usa la chiave che vi si trova.

Il server localhost è irraggiungibile o instabile

Coolify raggiunge il server dalla sua rete Docker. Una regola ufw limit 22/tcp o una restrizione di SSH al solo tuo indirizzo può bloccarlo. Sostituisci il limite con sudo ufw allow 22/tcp, oppure autorizza la rete di Coolify:

Terminale
docker network inspect coolify --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw allow from SOTTORETE to any port 22 proto tcp

Sostituisci SOTTORETE con il valore mostrato.

Il proxy non si avvia: address already in use

Un altro servizio usa la porta 80 o 443:

Terminale
sudo ss -ltnp | grep -E ':(80|443) '

Arresta e disattiva questo servizio, poi riavvia il proxy.

Il proxy è raggiungibile solo in locale

Verifica che /etc/docker/daemon.json non contenga "ip": "127.0.0.1" né host_binding_ipv4. Rimuovi queste chiavi, riavvia Docker, poi il proxy.

Il certificato non è valido (TRAEFIK DEFAULT CERT)

Let's Encrypt non è riuscito a convalidare il dominio. Controlla i record A e AAAA, poi l'accesso alla porta 80 dall'esterno. Se il dominio passa dal proxy di Cloudflare, disattivalo per il tempo della convalida oppure usa una challenge DNS. Se la porta resta irraggiungibile e sul server è tutto corretto, contatta il supporto dalla tua area clienti.

Errore 502 Bad Gateway

Il proxy raggiunge il container, ma non l'applicazione. Verifica che Ports Exposes corrisponda alla porta reale dell'applicazione e che questa ascolti su 0.0.0.0 e non su 127.0.0.1.

no available server

Traefik non trova alcun container integro per questo dominio. Controlla lo stato della distribuzione, il controllo di integrità dell'applicazione e l'ortografia del dominio in Domains.

La porta 8000 resta accessibile da Internet

Il file di personalizzazione non viene applicato. Verifica la sua posizione e la sua sintassi, poi applicalo come root:

Terminale
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config --quiet
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml up -d --remove-orphans

Il server rallenta molto durante una distribuzione

La compilazione consuma le risorse del server. Distribuisci un'immagine già pronta, compila altrove (ad esempio nella tua CI) oppure aumenta le risorse.

Invalid MAC dopo un ripristino

La chiave APP_KEY non corrisponde a quella del backup. Rimetti la chiave salvata in /data/coolify/source/.env, poi riesegui il programma di installazione con la stessa versione.

Riferimenti