Ir al contenido

Manual mestre: Desplegament i gestió de Plane (Edició Prime)

Guia tècnica integral per al desplegament de Plane Commercial/Prime Edition en Linux, configuració DNS amb Cloudflare i administració mitjançant prime-cli.

0lectures

  1. Requisits previs i preparació de l'entorn
  2. Instal·lació correcta de Docker Engine i Compose V2
  3. Configuració de DNS i SSL (Cloudflare)
  4. Instal·lació i posta en marxa de Plane
  5. Manual de referència de l'eina Prime CLI
  6. Resolució de problemes comuns

Per garantir un desplegament estable i lliure de conflictes en els ports principals (80 i 443), cal inicialitzar la instància en un servidor net:

  • Sistema Operatiu Recomanat: Ubuntu Server 20.04 LTS, 22.04 LTS o 24.04 LTS.
  • Recursos Mínims Recomanats: 4 GB de memòria RAM i 2 vCPUs (es suggereixen 8 GB de RAM per a entorns de producció activa).
  • Dominio Dedicat: Un registre DNS apuntant a la IP pública de l'host (ex. plane.portelcore.com).

2. Instal·lació Correcta de Docker Engine i Compose V2

Sección titulada «2. Instalación Correcta de Docker Engine y Compose V2»

[!IMPORTANT] Es desaconsella l'ús directe de apt install docker.io en repositoris bàsics d'Ubuntu, ja que instal·la paquets obsolets i incompatibles amb el backend de Plane. Segueix aquest procediment estandaritzat per instal·lar el motor oficial.

Ventana de terminal
sudo apt-get remove docker docker-engine docker.io containerd runc

2.2. Configuració del Repositori Oficial de Docker

Sección titulada «2.2. Configuración del Repositorio Oficial de Docker»

Afegeix les claus GPG del repositori oficial segur de 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. Instal·lació del Motor i el 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 que el comand d'orquestació de Docker Compose V2 estigui correctament integrat:

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

Perquè el desplegament funcioni correctament sota el paràmetre d'enrutament --behind-proxy, realitza la configuració al teu panell d'administració DNS de Cloudflare:

  1. Registre DNS (A): Crea una entrada A per al teu subdomini (plane) resolent cap a l'adreça IP pública del teu servidor.
  2. Estat del Proxy: Assegura't que el núvol naranja estigui actiu (Proxied).
  3. Criptografia SSL/TLS: Configura el mode de xifratge a Full o Full (Strict) al panell de Cloudflare.

4. Instal·lació i posada en marxa de Plane

Sección titulada «4. Instalación y Puesta en Marcha de Plane»
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. Execució de l'instal·lador en mode proxy

Sección titulada «4.2. Ejecución del Instalador en Modo Proxy»

Aquest pas és crític per omitir l'autogestió de certificats TLS locals en Plane i delegar el SSL al nostre proxy segur:

Ventana de terminal
sudo ./setup.sh --behind-proxy --domain="plane.portelcore.com"

L'script descarregarà les imatges dels serveis base (valkey, postgres, minio, core backend i frontend) i aixecarà els contenidors en segon pla.


L'edició Plane Prime s'administra centralment mitjançant la interfície de línia de comandes prime-cli, instal·lada a /bin/prime-cli.

Sintaxi d'execució:

Ventana de terminal
sudo prime-cli [comando]
  • prime-cli start: Encesa tots els contenidors definits en l'stack. Útil si l'host s'ha reiniciat.
  • prime-cli stop: Atura ordenadament els contenidors de Plane. S'ha d'executar sempre abans de manteniments de l'host.
  • prime-cli restart: Aplica un reinici complet als contenidors operatius davant ralentitzacions.
  • prime-cli configure: Obre un menú interactiu a la consola per gestionar variables d'entorn com SMTP, emmagatzematge S3/MinIO corporatiu i secrets de l'aplicació.
  • prime-cli upgrade: Actualitza Plane a l'última versió disponible del canal oficial, executant migracions de base de dades. Es suggereix realitzar una còpia de seguretat completa abans de la seva execució.
  • prime-cli repair: Restableix i repareix dependències o imatges corruptes si l'inici de l'aplicació falla.
  • prime-cli update-cli: Actualitza de manera independent l'eina de gestió prime-cli.

C. Estratègia de Còpies de Seguretat

Sección titulada «C. Estrategia de Respaldos»
  • prime-cli backup: Genera un fitxer comprimit .tar.gz o .zip amb la base de dades MySQL/Postgres local, fitxers adjunts de tasques i la configuració del fitxer .env. Emmagatzemat per defecte a /opt/plane/backups.
  • prime-cli restore: Sobrescriu l'estat actual carregant un punt de restauració previ.
  • prime-cli monitor: Mostra el volcat de traces de logs en temps real de tots els serveis.
  • prime-cli healthcheck: Realitza peticions de salut internes i informa de l'estat de Redis/Valkey, Postgres, Backend i els microserveis frontend.

Error: “Permission Denied” a la terminal de Docker

Sección titulada «Error: “Permission Denied” en la Terminal de Docker»
  • Causa: L'usuari de consola actual no té privilegis sobre el socket local /var/run/docker.sock.
  • Solució Permanent: Afegeix el teu usuari al grup operatiu de Docker:
    Ventana de terminal
    sudo usermod -aG docker $USER
    newgrp docker
  1. Inspecciona l'estat dels contenidors locals: sudo prime-cli healthcheck.
  2. Verifica que el proxy invers del contenidor de Plane responsi al port HTTP intern assignat a l'host.
  3. Assegura't que les directives del firewall de xarxa (p. ex. UFW) no estiguin bloquejant la comunicació interna.