Master-Handbuch: Bereitstellung und Verwaltung von Plane (Prime Edition)
Umfassender technischer Leitfaden für die Bereitstellung von Plane Commercial/Prime Edition unter Linux, DNS-Konfiguration mit Cloudflare und Verwaltung mittels prime-cli.
🗺️ Deployment-Roadmap
Sección titulada «🗺️ Mapa de Ruta del Despliegue»- Voraussetzungen und Vorbereitung der Umgebung
- Korrekte Installation von Docker Engine und Compose V2
- DNS- und SSL-Konfiguration (Cloudflare)
- Installation und Inbetriebnahme von Plane
- Referenzhandbuch des Prime CLI-Tools
- Fehlerbehebung bei häufigen Problemen
1. Voraussetzungen und Umgebungsvorbereitung
Sección titulada «1. Requisitos Previos y Preparación del Entorno»Um eine stabile und konfliktfreie Bereitstellung auf den Hauptports (80 und 443) zu gewährleisten, muss die Instanz auf einem sauberen Server initialisiert werden:
- Empfohlenes Betriebssystem: Ubuntu Server 20.04 LTS, 22.04 LTS oder 24.04 LTS.
- Empfohlene Mindestressourcen: 4 GB RAM und 2 vCPUs (für aktive Produktionsumgebungen werden 8 GB RAM empfohlen).
- Dedizierte Domain: Ein DNS-Eintrag, der auf die öffentliche IP des Hosts verweist (z. B.
plane.portelcore.com).
2. Korrekte Installation von Docker Engine und Compose V2
Sección titulada «2. Instalación Correcta de Docker Engine y Compose V2»[!IMPORTANT] Es wird davon abgeraten,
apt install docker.iodirekt in grundlegenden Ubuntu-Repositorys zu verwenden, da es veraltete und mit der Plane-Backend-Inkompatibilität installierte Pakete gibt. Folgen Sie diesem standardisierten Verfahren, um den offiziellen Motor zu installieren.
2.1. Bereinigung von Versionskonflikten (Säuberung)
Sección titulada «2.1. Depuración de Versiones Conflictivas (Limpieza)»sudo apt-get remove docker docker-engine docker.io containerd runc2.2. Konfiguration des offiziellen Docker-Repositorys
Sección titulada «2.2. Configuración del Repositorio Oficial de Docker»Fügen Sie die GPG-Schlüssel des sicheren offiziellen Docker-Repositorys hinzu:
# 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. Installation der Engine und des Compose-Plugins
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. Validierung der aktualisierten Version
Sección titulada «2.4. Validación de la Versión Modernizada»Überprüfen Sie, ob der Orchestrierungsbefehl von Docker Compose V2 korrekt integriert ist:
docker compose version# Salida esperada: Docker Compose version v2.x.x3. DNS- und SSL-Konfiguration (Cloudflare)
Sección titulada «3. Configuración de DNS y SSL (Cloudflare)»Damit das Deployment unter dem Routing-Parameter --behind-proxy korrekt funktioniert, führen Sie die Konfiguration in Ihrem Cloudflare DNS-Administrationspanel durch:
- DNS-Eintrag (A): Erstellen Sie einen
AEintrag für Ihre Subdomain (plane), der auf die öffentliche IP-Adresse Ihres Servers verweist. - Proxy-Status: Stellen Sie sicher, dass die orangefarbene Wolke aktiviert ist (Proxied).
- SSL/TLS-Verschlüsselung: Konfigurieren Sie den Verschlüsselungsmodus im Cloudflare-Panel auf Full oder Full (Strict).
4. Installation und Inbetriebnahme von Plane
Sección titulada «4. Instalación y Puesta en Marcha de Plane»4.1. Erstellung des Arbeitsverzeichnisses
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. Ausführung des Installers im Proxy-Modus
Sección titulada «4.2. Ejecución del Instalador en Modo Proxy»Dieser Schritt ist entscheidend, um die Selbstverwaltung lokaler TLS-Zertifikate in Plane zu überspringen und SSL an unseren sicheren Proxy zu delegieren:
sudo ./setup.sh --behind-proxy --domain="plane.portelcore.com"Das Skript lädt die Images der Basisdienste (Valkey, Postgres, MinIO, Core-Backend und Frontend) herunter und startet die Container im Hintergrund.
5. Referenzhandbuch für das Prime CLI-Tool
Sección titulada «5. Manual de Referencia de la Herramienta Prime CLI»Die Plane Prime-Edition wird zentral über die Kommandozeilen-Schnittstelle prime-cli verwaltet, die auf /bin/prime-cli installiert ist.
Ausführungssyntax:
sudo prime-cli [comando]A. Steuerung des Stack-Lebenszyklus
Sección titulada «A. Control del Ciclo de Vida del Stack»prime-cli start: Startet alle im Stack definierten Container. Nützlich, wenn der Host neu gestartet wurde.prime-cli stop: Stoppt die Plane-Container geordnet. Muss immer vor Wartungsarbeiten am Host ausgeführt werden.prime-cli restart: Führt bei Verlangsamungen einen vollständigen Neustart der laufenden Container durch.
B. Erweiterte Konfiguration und Wartung
Sección titulada «B. Configuración y Mantenimiento Avanzado»prime-cli configure: Öffnet ein interaktives Konsolenmenü zur Verwaltung von Umgebungsvariablen wie SMTP, S3/MinIO-Unternehmensspeicher und Applikations-Secrets.prime-cli upgrade: Aktualisiert Plane auf die neueste verfügbare Version des offiziellen Kanals durch Ausführung von Datenbankmigrationen. Es wird empfohlen, vor der Ausführung ein vollständiges Backup zu erstellen.prime-cli repair: Setzt Abhängigkeiten oder beschädigte Images zurück und repariert sie, falls der Start der Anwendung fehlschlägt.prime-cli update-cli: Aktualisiert das Management-Toolprime-cliunabhängig.
C. Backup-Strategie
Sección titulada «C. Estrategia de Respaldos»prime-cli backup: Erstellt eine komprimierte Datei.tar.gzoder.zipmit der lokalen MySQL/Postgres-Datenbank, Aufgabenanhängen und der Konfiguration der Datei.env. Standardmäßig gespeichert unter/opt/plane/backups.prime-cli restore: Überschreibt den aktuellen Status durch Laden eines vorherigen Wiederherstellungspunkts.
D. Diagnose und Überwachung
Sección titulada «D. Diagnóstico y Monitoreo»prime-cli monitor: Zeigt den Echtzeit-Log-Trace-Dump aller Dienste an.prime-cli healthcheck: Führt interne Health-Checks durch und meldet den Status von Redis/Valkey, Postgres, dem Backend und den Frontend-Microservices.
6. Behebung häufiger Probleme
Sección titulada «6. Resolución de Problemas Comunes»Fehler: „Permission Denied“ im Docker-Terminal
Sección titulada «Error: “Permission Denied” en la Terminal de Docker»- Ursache: Der aktuelle Konsolenbenutzer verfügt über keine Berechtigungen für den lokalen Socket
/var/run/docker.sock. - Permanente Lösung: Füge deinen Benutzer zur Docker-Betriebsgruppe hinzu:
Ventana de terminal sudo usermod -aG docker $USERnewgrp docker
Fehler: 502 Bad Gateway (Cloudflare Edge)
Sección titulada «Error: 502 Bad Gateway (Cloudflare Edge)»- Überprüfe den Status der lokalen Container:
sudo prime-cli healthcheck. - Stellen Sie sicher, dass der Reverse-Proxy des Plane-Containers auf dem zugewiesenen internen HTTP-Port des Hosts antwortet.
- Stellen Sie sicher, dass die Netzwerk-Firewall-Richtlinien (z. B. UFW) die interne Kommunikation nicht blockieren.

