Installation mit Docker Compose

Diese Anleitung beschreibt den empfohlenen Serverbetrieb mit fertigen Docker-Images. Sie richtet sich an technisch versierte Anwender, die FreeCAD-PLM auf einem kleinen Server oder im LAN betreiben wollen. Es wird davon abgeraten, den Dienst öffentlich im Internet bereitzustellen.

Wenn du FreeCAD-PLM nur benutzt und nicht betreibst, brauchst du diese Seite nicht. Für Anwender beginnt der Einstieg bei Web-UI Benutzung.

Zielbild

Der Compose-Stack besteht aus:

• web: Django-Webanwendung mit Gunicorn,
• worker: Hintergrundworker mit FreeCADCmd für Analyse, Exporte und PNG-Ansichten,
• db: PostgreSQL,
• storage/: lokale CAD-, Upload- und Artefaktdateien,
• staticfiles/: generierte Django-Static-Dateien.

Web und Worker nutzen getrennte Images:

git.home.schumbi.de/ralf/freecad-plm-web:latest
git.home.schumbi.de/ralf/freecad-plm-worker:latest

Das Web-Image ist kleiner und enthält kein FreeCAD. Das Worker-Image enthält FreeCAD/FreeCADCmd.

Voraussetzungen

Auf dem Server brauchst du:

• Docker,
• Docker Compose Plugin,
• Zugriff auf die Image-Registry,
• einen lokalen Ordner für Compose-Datei, .env, storage/ und staticfiles/,
• genuegend Speicherplatz für CAD-Dateien, Artefakte und PostgreSQL.

Plane den Speicherplatz großzügig. CAD-Revisionen werden nicht überschrieben, und Artefakte wie STEP, STL, PNG oder 3MF kommen zusätzlich dazu.

Repository holen

git clone ssh://home.schumbi.de/ralf/freecad-plm.git /opt/freecad-plm
cd /opt/freecad-plm
cp .env.example .env

oder

git clone https://git.home.schumbi.de/ralf/freecad-plm.git
cd /opt/freecad-plm
cp .env.example .env

Wenn du nur mit dem fertigen Image arbeitest, brauchst du trotzdem die Compose-Datei Docker-compose.image.yml und die Beispielkonfiguration aus dem Repo.

.env konfigurieren

Öffne .env und setze mindestens diese Werte:

DJANGO_SECRET_KEY=replace-with-a-long-random-secret
DJANGO_ALLOWED_HOSTS=plm.example.local,localhost,127.0.0.1
DJANGO_CSRF_TRUSTED_ORIGINS=https://plm.example.local
DJANGO_SECURE_SSL_REDIRECT=0
DJANGO_SECURE_HSTS_SECONDS=0
DJANGO_SESSION_COOKIE_SECURE=1
DJANGO_CSRF_COOKIE_SECURE=1

POSTGRES_PASSWORD=replace-with-a-strong-database-password

PLM_HTTP_PORT=8000
PLM_WEB_IMAGE=git.home.schumbi.de/ralf/freecad-plm-web:latest
PLM_WORKER_IMAGE=git.home.schumbi.de/ralf/freecad-plm-worker:latest
PLM_USER=plm
PLM_UID=1000
PLM_GID=1000
FREECADCMD_COMMAND=freecadcmd

Wichtige Hinweise:

• DJANGO_ALLOWED_HOSTS muss den Hostnamen enthalten, unter dem du das PLM aufrufst.
• DJANGO_CSRF_TRUSTED_ORIGINS muss die HTTPS-Origin enthalten, wenn ein Reverse Proxy davor sitzt.
• PLM_HTTP_PORT ist der Host-Port, auf dem der Webcontainer erreichbar wird.
• PLM_USER=plm passt zum Runtime-User im Image.
• PLM_UID und PLM_GID dokumentieren, welchem Host-User die lokalen Verzeichnisse gehören sollen.

Die Beispieldatei findest du auch hier: .env.example

Lokale Verzeichnisse anlegen

Die CAD-Daten sollen bewusst außerhalb des Containers liegen:

mkdir -p storage staticfiles
sudo chown -R 1000:1000 storage staticfiles

storage/ enthält die wichtigen Nutzdaten: Revisionen, Projektstände, Artefakte, Fertigungsdateien und Vorschaubilder. Dieses Verzeichnis muss gesichert werden.

staticfiles/ enthält neu generierbare CSS-/JS-/Admin-Dateien. Es ist praktisch, aber nicht so kritisch wie storage/ und die Datenbank.

Start

docker compose -f docker-compose.image.yml pull
docker compose -f docker-compose.image.yml up -d

Beim Start führt der Webcontainer automatisch aus:

• Datenbankmigrationen,
• collectstatic,
• Start von Gunicorn.

Der Worker verarbeitet im Hintergrund Export- und Analysejobs.

Erster Admin-Benutzer

Nach dem ersten Start Rollen anlegen und einen Admin erzeugen:

docker compose -f docker-compose.image.yml exec web python manage.py setup_plm_roles
docker compose -f docker-compose.image.yml exec web python manage.py createsuperuser

Danach kannst du dich im Browser unter http://server:port/login/ anmelden.

Update

Wenn neue Images gebaut wurden:

cd /opt/freecad-plm
git pull
docker compose -f docker-compose.image.yml pull
docker compose -f docker-compose.image.yml up -d

Das git pull aktualisiert Compose-Datei, .env.example und sonstige Begleitdateien. Das docker compose pull holt die neuen Images.

Reverse Proxy

Wenn FreeCAD-PLM hinter Nginx, Nginx Proxy Manager oder einem anderen Reverse Proxy per HTTPS läuft, setze in .env:

DJANGO_ALLOWED_HOSTS=plm.example.local,localhost,127.0.0.1
DJANGO_CSRF_TRUSTED_ORIGINS=https://plm.example.local
DJANGO_SESSION_COOKIE_SECURE=1
DJANGO_CSRF_COOKIE_SECURE=1

Der Proxy muss mindestens diese Header weitergeben:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;

Außerdem sollte die Upload-Größe zum Projekt passen, zum Beispiel:

client_max_body_size 512m;

Nach .env-Änderungen:

docker compose -f docker-compose.image.yml up -d --force-recreate web worker

Backups

Sichere mindestens:

• PostgreSQL-Datenbank,
• storage/,
• deine .env,
• die verwendete docker-compose.image.yml.

Ein einfaches Datenbank-Backup:

docker compose -f docker-compose.image.yml exec db pg_dump -U freecad_plm freecad_plm > freecad_plm.sql

Dazu gehört ein Dateibackup von storage/. Datenbank und Storage gehören zusammen, weil die Datenbank auf Dateien im Storage verweist.

Wichtig: Ein Backup nur von storage/ ist unvollständig, weil dann Metadaten, Benutzer, Projektstände und Revisionsbeziehungen fehlen. Ein Backup nur von PostgreSQL ist ebenfalls unvollständig, weil dann die eigentlichen Dateien fehlen.