Ir al contenido

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.

0letture

  1. Requisiti Preliminari e Preparazione dell'Ambiente
  2. Installazione Corretta di Docker Engine e Compose V2
  3. Configurazione DNS e SSL (Cloudflare)
  4. Installazione e messa in servizio di Plane
  5. Manuale di riferimento dello strumento Prime CLI
  6. Risoluzione dei problemi comuni

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.io nei 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)»
Ventana de terminal
sudo apt-get remove docker docker-engine docker.io containerd runc

2.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:

Ventana de terminal
# Instalar dependencias previas
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
# Crear el llavero seguro en el sistema
sudo install -m 0755 -d /etc/apt/keyrings
# Descargar e importar la clave GPG
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Añadir el repositorio a las fuentes estables de Apt
echo \
"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/null

2.3. Installazione del Motore e del Plugin Compose

Sección titulada «2.3. Instalación del Motor y Plugin Compose»
Ventana de terminal
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Verifica che il comando di orchestrazione di Docker Compose V2 sia correttamente integrato:

Ventana de terminal
docker compose version
# Salida esperada: Docker Compose version v2.x.x

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:

  1. Record DNS (A): Crea un record A per il tuo sottodominio (plane) risolvendo verso l'indirizzo IP pubblico del tuo server.
  2. Stato del Proxy: Assicurati che la nuvola arancione sia attiva (Proxied).
  3. Crittografia SSL/TLS: Configura la modalità di cifratura su Full o Full (Strict) nel pannello di Cloudflare.

Ventana de terminal
mkdir plane-selfhost && cd plane-selfhost
curl -fsSL https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh -o setup.sh
chmod +x setup.sh

4.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:

Ventana de terminal
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:

Ventana de terminal
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.
  • 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 gestione prime-cli.
  • prime-cli backup: Genera un file compresso .tar.gz o .zip con 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.
  • 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.

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 $USER
    newgrp docker
  1. Ispeziona lo stato dei container locali: sudo prime-cli healthcheck.
  2. Verifica che il reverse proxy del container di Plane risponda sulla porta HTTP interna assegnata nell'host.
  3. Assicurati che le direttive del firewall di rete (es. UFW) non blocchino la comunicazione interna.