Ir al contenido

Manual Maestro: Despliegue y Gestión de Plane (Edición Prime)

Guía técnica integral para el despliegue de Plane Commercial/Prime Edition en Linux, configuración DNS con Cloudflare y administración mediante prime-cli.

0lecturas

  1. Requisitos Previos y Preparación del Entorno
  2. Instalación Correcta de Docker Engine y Compose V2
  3. Configuración de DNS y SSL (Cloudflare)
  4. Instalación y Puesta en Marcha de Plane
  5. Manual de Referencia de la Herramienta Prime CLI
  6. Resolución de Problemas Comunes

1. Requisitos Previos y Preparación del Entorno

Sección titulada «1. Requisitos Previos y Preparación del Entorno»

Para garantizar un despliegue estable y libre de conflictos en los puertos principales (80 y 443), se requiere inicializar la instancia en un servidor limpio:

  • Sistema Operativo Recomendado: Ubuntu Server 20.04 LTS, 22.04 LTS o 24.04 LTS.
  • Recursos Mínimos Recomendados: 4 GB de memoria RAM y 2 vCPUs (se sugieren 8 GB de RAM para entornos de producción activa).
  • Dominio Dedicado: Un registro DNS apuntando a la IP pública del host (ej. plane.portelcore.com).

2. Instalación Correcta de Docker Engine y Compose V2

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

[!IMPORTANT] Se desaconseja el uso directo de apt install docker.io en repositorios básicos de Ubuntu, ya que instala paquetes obsoletos e incompatibles con el backend de Plane. Sigue este procedimiento estandarizado para instalar el motor oficial.

2.1. Depuración de Versiones Conflictivas (Limpieza)

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. Configuración del Repositorio Oficial de Docker

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

Añade las claves GPG del repositorio oficial seguro 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. Instalación del Motor y 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 comando de orquestación de Docker Compose V2 esté correctamente integrado:

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

Para que el despliegue funcione correctamente bajo el parámetro de enrutamiento --behind-proxy, realiza la configuración en tu panel de administración DNS de Cloudflare:

  1. Registro DNS (A): Crea una entrada A para tu subdominio (plane) resolviendo hacia la dirección IP pública de tu servidor.
  2. Estado del Proxy: Asegura que la nube naranja esté activa (Proxied).
  3. Encriptación SSL/TLS: Configura el modo de cifrado en Full o Full (Strict) en el panel de 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. Ejecución del Instalador en Modo Proxy

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

Este paso es crítico para omitir la autogestión de certificados TLS locales en Plane y delegar el SSL a nuestro proxy seguro:

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

El script descargará las imágenes de los servicios base (valkey, postgres, minio, core backend y frontend) y levantará los contenedores en segundo plano.


5. Manual de Referencia de la Herramienta Prime CLI

Sección titulada «5. Manual de Referencia de la Herramienta Prime CLI»

La edición Plane Prime se administra centralizadamente mediante la interfaz de línea de comandos prime-cli, instalada en /bin/prime-cli.

Sintaxis de ejecución:

Ventana de terminal
sudo prime-cli [comando]
  • prime-cli start: Arranca todos los contenedores definidos en el stack. Útil si el host se ha reiniciado.
  • prime-cli stop: Detiene ordenadamente los contenedores de Plane. Debe ejecutarse siempre antes de mantenimientos del host.
  • prime-cli restart: Aplica un reinicio completo a los contenedores operativos ante ralentizaciones.
  • prime-cli configure: Abre un menú interactivo en consola para gestionar variables de entorno como SMTP, almacenamiento S3/MinIO corporativo y secretos de la aplicación.
  • prime-cli upgrade: Actualiza Plane a la última versión disponible del canal oficial, ejecutando migraciones de base de datos. Se sugiere realizar un respaldo completo antes de su ejecución.
  • prime-cli repair: Restablece y repara dependencias o imágenes corruptas si el inicio de la aplicación falla.
  • prime-cli update-cli: Actualiza de manera independiente la herramienta de gestión prime-cli.
  • prime-cli backup: Genera un archivo comprimido .tar.gz o .zip con la base de datos MySQL/Postgres local, archivos adjuntos de tareas y la configuración del archivo .env. Almacenado por defecto en /opt/plane/backups.
  • prime-cli restore: Sobrescribe el estado actual cargando un punto de restauración previo.
  • prime-cli monitor: Muestra el volcado de trazas de logs en tiempo real de todos los servicios.
  • prime-cli healthcheck: Realiza peticiones de salud internas y reporta el estado de Redis/Valkey, Postgres, Backend y los microservicios frontend.

Error: “Permission Denied” en la Terminal de Docker

Sección titulada «Error: “Permission Denied” en la Terminal de Docker»
  • Causa: El usuario de consola actual carece de privilegios sobre el socket local /var/run/docker.sock.
  • Solución Permanente: Añade tu usuario al grupo operativo de Docker:
    Ventana de terminal
    sudo usermod -aG docker $USER
    newgrp docker
  1. Inspecciona el estado de los contenedores locales: sudo prime-cli healthcheck.
  2. Verifica que el proxy reverso del contenedor de Plane responda en el puerto HTTP interno asignado en el host.
  3. Asegura que las directivas del cortafuegos de red (e.g. UFW) no estén bloqueando la comunicación interna.