Manuale Maestro: Deployment e Gestione di Plane (Edizione Prime)
Guida tecnica completa per il deployment di Plane Commercial/Prime Edition su Linux, configurazione DNS con Cloudflare e amministrazione tramite prime-cli.
🗺️ Roadmap del Deployment
Sección titulada «🗺️ Mapa de Ruta del Despliegue»- Requisiti Preliminari e Preparazione dell'Ambiente
- Installazione Corretta di Docker Engine e Compose V2
- Configurazione DNS e SSL (Cloudflare)
- Installazione e messa in servizio di Plane
- Manuale di riferimento dello strumento Prime CLI
- Risoluzione dei problemi comuni
1. Prerequisiti e Preparazione dell'Ambiente
Sección titulada «1. Requisitos Previos y Preparación del Entorno»Per garantire un deployment stabile e privo di conflitti nelle porte principali (80 e 443), è necessario inizializzare l'istanza su un server pulito:
- Sistema Operativo Raccomandato: Ubuntu Server 20.04 LTS, 22.04 LTS o 24.04 LTS.
- Risorse Minime Raccomandate: 4 GB di memoria RAM e 2 vCPU (si suggeriscono 8 GB di RAM per ambienti di produzione attiva).
- Dominio Dedicato: Un record DNS che punta all'IP pubblica dell'host (es.
plane.portelcore.com).
2. Installazione Corretta di Docker Engine e Compose V2
Sección titulada «2. Instalación Correcta de Docker Engine y Compose V2»[!IMPORTANT] Si sconsiglia l'uso diretto di
apt install docker.ionei repository di base di Ubuntu, poiché installa pacchetti obsoleti e incompatibili con il backend di Plane. Seguire questa procedura standardizzata per installare il motore ufficiale.
2.1. Rimozione delle Versioni in Conflitto (Pulizia)
Sección titulada «2.1. Depuración de Versiones Conflictivas (Limpieza)»sudo apt-get remove docker docker-engine docker.io containerd runc2.2. Configurazione del Repository Ufficiale di Docker
Sección titulada «2.2. Configuración del Repositorio Oficial de Docker»Aggiungi le chiavi GPG del repository ufficiale sicuro di Docker:
# Instalar dependencias previassudo apt-get updatesudo apt-get install ca-certificates curl gnupg -y
# Crear el llavero seguro en el sistemasudo install -m 0755 -d /etc/apt/keyrings
# Descargar e importar la clave GPGcurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpgsudo chmod a+r /etc/apt/keyrings/docker.gpg
# Añadir el repositorio a las fuentes estables de Aptecho \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null2.3. Installazione del Motore e del Plugin Compose
Sección titulada «2.3. Instalación del Motor y Plugin Compose»sudo apt-get updatesudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y2.4. Convalida della Versione Aggiornata
Sección titulada «2.4. Validación de la Versión Modernizada»Verifica che il comando di orchestrazione di Docker Compose V2 sia correttamente integrato:
docker compose version# Salida esperada: Docker Compose version v2.x.x3. Configurazione di DNS e SSL (Cloudflare)
Sección titulada «3. Configuración de DNS y SSL (Cloudflare)»Per far sì che il deployment funzioni correttamente sotto il parametro di routing --behind-proxy, esegui la configurazione nel tuo pannello di amministrazione DNS di Cloudflare:
- Record DNS (A): Crea un record
Aper il tuo sottodominio (plane) risolvendo verso l'indirizzo IP pubblico del tuo server. - Stato del Proxy: Assicurati che la nuvola arancione sia attiva (Proxied).
- Crittografia SSL/TLS: Configura la modalità di cifratura su Full o Full (Strict) nel pannello di Cloudflare.
4. Installazione e Avvio di Plane
Sección titulada «4. Instalación y Puesta en Marcha de Plane»4.1. Creazione della Directory di Lavoro
Sección titulada «4.1. Creación del Directorio de Trabajo»mkdir plane-selfhost && cd plane-selfhostcurl -fsSL https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh -o setup.shchmod +x setup.sh4.2. Esecuzione dell'Installer in Modalità Proxy
Sección titulada «4.2. Ejecución del Instalador en Modo Proxy»Questo passaggio è fondamentale per ignorare l'autogestione dei certificati TLS locali in Plane e delegare l'SSL al nostro proxy sicuro:
sudo ./setup.sh --behind-proxy --domain="plane.portelcore.com"Lo script scaricherà le immagini dei servizi di base (valkey, postgres, minio, core backend e frontend) e avvierà i container in background.
5. Manuale di Riferimento dello Strumento Prime CLI
Sección titulada «5. Manual de Referencia de la Herramienta Prime CLI»L'edizione Plane Prime viene gestita centralmente tramite l'interfaccia della riga di comando prime-cli, installata in /bin/prime-cli.
Sintassi di esecuzione:
sudo prime-cli [comando]A. Controllo del Ciclo di Vita dello Stack
Sección titulada «A. Control del Ciclo de Vida del Stack»prime-cli start: Avvia tutti i container definiti nello stack. Utile se l'host è stato riavviato.prime-cli stop: Ferma in modo ordinato i container di Plane. Deve essere sempre eseguito prima della manutenzione dell'host.prime-cli restart: Applica un riavvio completo ai container operativi in caso di rallentamenti.
B. Configurazione e Manutenzione Avanzata
Sección titulada «B. Configuración y Mantenimiento Avanzado»prime-cli configure: Apre un menu interattivo nella console per gestire le variabili d'ambiente come SMTP, l'archiviazione S3/MinIO aziendale e i segreti dell'applicazione.prime-cli upgrade: Aggiorna Plane all'ultima versione disponibile del canale ufficiale, eseguendo migrazioni del database. Si consiglia di effettuare un backup completo prima dell'esecuzione.prime-cli repair: Ripristina e ripara dipendenze o immagini corrotte se l'avvio dell'applicazione fallisce.prime-cli update-cli: Aggiorna in modo indipendente lo strumento di gestioneprime-cli.
C. Strategia di Backup
Sección titulada «C. Estrategia de Respaldos»prime-cli backup: Genera un file compresso.tar.gzo.zipcon il database MySQL/Postgres locale, gli allegati dei task e la configurazione del file.env. Memorizzato per impostazione predefinita in/opt/plane/backups.prime-cli restore: Sovrascrive lo stato attuale caricando un punto di ripristino precedente.
D. Diagnostica e Monitoraggio
Sección titulada «D. Diagnóstico y Monitoreo»prime-cli monitor: Mostra il dump delle tracce dei log in tempo reale di tutti i servizi.prime-cli healthcheck: Esegue controlli di stato interni e riporta lo stato di Redis/Valkey, Postgres, Backend e dei microservizi frontend.
6. Risoluzione dei Problemi Comuni
Sección titulada «6. Resolución de Problemas Comunes»Errore: “Permission Denied” nel Terminale di Docker
Sección titulada «Error: “Permission Denied” en la Terminal de Docker»- Causa: L'utente della console attuale non dispone di privilegi sul socket locale
/var/run/docker.sock. - Soluzione Permanente: Aggiungi il tuo utente al gruppo operativo di Docker:
Ventana de terminal sudo usermod -aG docker $USERnewgrp docker
Errore: 502 Bad Gateway (Cloudflare Edge)
Sección titulada «Error: 502 Bad Gateway (Cloudflare Edge)»- Ispeziona lo stato dei container locali:
sudo prime-cli healthcheck. - Verifica che il reverse proxy del container di Plane risponda sulla porta HTTP interna assegnata nell'host.
- Assicurati che le direttive del firewall di rete (es. UFW) non blocchino la comunicazione interna.

