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.
🗺️ Mapa de Ruta del Despliegue
Sección titulada «🗺️ Mapa de Ruta del Despliegue»- Requisitos Previos y Preparación del Entorno
- Instalación Correcta de Docker Engine y Compose V2
- Configuración de DNS y SSL (Cloudflare)
- Instalación y Puesta en Marcha de Plane
- Manual de Referencia de la Herramienta Prime CLI
- 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.ioen 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)»sudo apt-get remove docker docker-engine docker.io containerd runc2.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:
# 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. Instalación del Motor y 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. Validación de la Versión Modernizada
Sección titulada «2.4. Validación de la Versión Modernizada»Verifica que el comando de orquestación de Docker Compose V2 esté correctamente integrado:
docker compose version# Salida esperada: Docker Compose version v2.x.x3. Configuración de DNS y SSL (Cloudflare)
Sección titulada «3. Configuración de DNS y SSL (Cloudflare)»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:
- Registro DNS (A): Crea una entrada
Apara tu subdominio (plane) resolviendo hacia la dirección IP pública de tu servidor. - Estado del Proxy: Asegura que la nube naranja esté activa (Proxied).
- Encriptación SSL/TLS: Configura el modo de cifrado en Full o Full (Strict) en el panel de Cloudflare.
4. Instalación y Puesta en Marcha de Plane
Sección titulada «4. Instalación y Puesta en Marcha de Plane»4.1. Creación del Directorio de Trabajo
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. 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:
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:
sudo prime-cli [comando]A. Control del Ciclo de Vida del Stack
Sección titulada «A. Control del Ciclo de Vida del Stack»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.
B. Configuración y Mantenimiento Avanzado
Sección titulada «B. Configuración y Mantenimiento Avanzado»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ónprime-cli.
C. Estrategia de Respaldos
Sección titulada «C. Estrategia de Respaldos»prime-cli backup: Genera un archivo comprimido.tar.gzo.zipcon 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.
D. Diagnóstico y Monitoreo
Sección titulada «D. Diagnóstico y Monitoreo»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.
6. Resolución de Problemas Comunes
Sección titulada «6. Resolución de Problemas Comunes»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 $USERnewgrp docker
Error: 502 Bad Gateway (Cloudflare Edge)
Sección titulada «Error: 502 Bad Gateway (Cloudflare Edge)»- Inspecciona el estado de los contenedores locales:
sudo prime-cli healthcheck. - Verifica que el proxy reverso del contenedor de Plane responda en el puerto HTTP interno asignado en el host.
- Asegura que las directivas del cortafuegos de red (e.g. UFW) no estén bloqueando la comunicación interna.

