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.
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
rooto con un utente che dispone disudo - 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:
dig +short A coolify.tuo-dominio.com
dig +short A app.tuo-dominio.com
dig +short AAAA coolify.tuo-dominio.comI 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:
sudo sshd -T | grep -i '^permitrootlogin'I valori prohibit-password, without-password e yes vanno bene. Se ottieni no, autorizza root solo tramite chiave:
echo 'PermitRootLogin prohibit-password' | sudo tee /etc/ssh/sshd_config.d/00-coolify.conf
sudo sshd -t
sudo systemctl reload sshMantieni 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:
sudo -i
mkdir -p /data/coolify/source
nano /data/coolify/source/docker-compose.custom.ymlIncolla questo contenuto:
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:
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.5Lo 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:
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:
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_SERVERIl 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:
grep '^APP_KEY=' /data/coolify/source/.envPasso 7: avviare il proxy
Apri Servers > localhost > Proxy. Traefik è il proxy predefinito.
In Configuration, rimuovi la riga seguente, inutile per questa configurazione, poi salva:
- '8080:8080'Clicca poi su Start Proxy, oppure riavvia il proxy se è già in esecuzione. Sul server, verifica che sia in ascolto:
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:
https://coolify.tuo-dominio.comLascia attivo Redirect HTTP to HTTPS, poi clicca su Save changes. Dopo qualche istante, apri https://coolify.tuo-dominio.com e controlla il certificato:
curl -I https://coolify.tuo-dominio.comVerifica 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:
nmap -Pn -p 22,80,443,6001,6002,8000,8080 IP_DEL_TUO_SERVERSolo 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.
- Apri Projects, crea un progetto chiamato
demo, poi aprilo. - Clicca su + New (o Create New Resource), poi scegli Docker Image.
- Inserisci l'immagine
nginx:1.30-alpinee continua. - In Ports Exposes, indica
80. - In Domains, clicca su Add domain, scegli
httpse inserisciapp.tuo-dominio.com. - Clicca su Deploy e segui i log della distribuzione.
Verifica poi il risultato:
curl -I https://app.tuo-dominio.comLa 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:
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | bash -s 4.7.5Non 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:
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:
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.5Indica 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:
docker restart coolifyL'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:
ssh-keygen -y -f /data/coolify/ssh/keys/id.root@host.docker.internal | sed 's/$/ coolify/' >> /root/.ssh/authorized_keysSe 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:
docker network inspect coolify --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw allow from SOTTORETE to any port 22 proto tcpSostituisci SOTTORETE con il valore mostrato.
Il proxy non si avvia: address already in use
Un altro servizio usa la porta 80 o 443:
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:
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-orphansIl 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.