Manual Mestre: Desdobramento e Gestão do Plane (Edição Prime)
Guia técnica integral para o desdobramento do Plane Commercial/Prime Edition no Linux, configuração DNS com Cloudflare e administração via prime-cli.
🗺️ Roteiro de Implantação
Sección titulada «🗺️ Mapa de Ruta del Despliegue»- Requisitos Prévios e Preparação do Ambiente
- Instalação Correta do Docker Engine e Compose V2
- Configuração de DNS e SSL (Cloudflare)
- Instalação e Lançamento do Plane
- Manual de Referência da Ferramenta Prime CLI
- Resolución de Problemas Comunes
1. Pré-requisitos e Preparação do Ambiente
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. Instalação Correta do Docker Engine e Compose V2
Sección titulada «2. Instalación Correcta de Docker Engine y Compose V2»[!IMPORTANT]\r\nDesaconselha-se o uso direto de
apt install docker.ioem repositórios básicos do Ubuntu, pois instala pacotes obsoletos e incompatíveis com o backend do Plane. Siga este procedimento padronizado para instalar o motor oficial.
2.1. Depuração de Versões Conflitantes (Limpeza)
Sección titulada «2.1. Depuración de Versiones Conflictivas (Limpieza)»sudo apt-get remove docker docker-engine docker.io containerd runc2.2. Configuração do Repositório Oficial do Docker
Sección titulada «2.2. Configuración del Repositorio Oficial de Docker»Adicione as chaves GPG do repositório oficial seguro do 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. Instalação do Motor e 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. Validação da Versão Modernizada
Sección titulada «2.4. Validación de la Versión Modernizada»Verifique se o comando de orquestração do Docker Compose V2 está corretamente integrado:
docker compose version# Salida esperada: Docker Compose version v2.x.x3. Configuração de DNS e 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 A para 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. Instalação e Inicialização do Plane
Sección titulada «4. Instalación y Puesta en Marcha de Plane»4.1. Criação do Diretório de Trabalho
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. Execução do Instalador em Modo Proxy
Sección titulada «4.2. Ejecución del Instalador en Modo Proxy»Este passo é crítico para omitir a autogestão de certificados TLS locais no Plane e delegar o SSL ao nosso proxy seguro:
sudo ./setup.sh --behind-proxy --domain="plane.portelcore.com"O script fará o download das imagens dos serviços base (valkey, postgres, minio, core backend e frontend) e iniciará os contêineres em segundo plano.
5. Manual de Referência da Ferramenta 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.
Sintaxe de execução:
sudo prime-cli [comando]A. Controle do Ciclo de Vida do 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. Configuração e Manutenção Avançada
Sección titulada «B. Configuración y Mantenimiento Avanzado»- É um comando para configurar o ambiente de desenvolvimento:
- 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.
C. Estratégia de Backups
Sección titulada «C. Estrategia de Respaldos»- 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.
D. Diagnóstico e Monitoramento
Sección titulada «D. Diagnóstico y Monitoreo»- prime-cli monitor: Mostra o registro de logs em tempo real de todos os serviços.
- prime-cli healthcheck: Realiza verificações internas e relata o estado de Redis/Valkey, Postgres, Backend e os microserviços frontend.
6. Resolução de Problemas Comuns
Sección titulada «6. Resolución de Problemas Comunes»Erro: “Permission Denied” no Terminal do Docker
Sección titulada «Error: “Permission Denied” en la Terminal de Docker»- Causa: O usuário de console atual carece de privilégios sobre o 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
Erro: 502 Bad Gateway (Cloudflare Edge)
Sección titulada «Error: 502 Bad Gateway (Cloudflare Edge)»- Inspeccione o estado dos contenedores locais:
sudo prime-cli healthcheck. - Verifique se o proxy reverso do contêiner do Plane responde na porta HTTP interna atribuída no host.
- Certifique-se de que as diretivas do firewall de rede (ex. UFW) não estejam bloqueando a comunicação interna.

