Magento Deployment richtig strukturieren

Ein sauberes Magento Deployment ist der entscheidende Unterschied zwischen einer stabilen Shopumgebung und einem Chaos aus Fehlermeldungen, Cache-Problemen und Downtime. Viele kleine Teams und Freelancer arbeiten noch manuell per FTP oder kopieren ganze Verzeichnisse, was bei einem komplexen Framework wie Magento schnell zu unvorhersehbarem Verhalten führt.

In diesem Artikel zeige ich, wie du einen professionellen Deployment-Prozess für Magento 2 aufsetzt – mit Git, Composer, Environment-Trennung, automatischen Builds und klaren Zuständigkeiten. Ziel ist, dass du deinen Code strukturiert, reproduzierbar und sicher auf Staging und Live bringst, ohne Abhängigkeiten manuell zu verwalten.

1. Warum ein durchdachtes Deployment so wichtig ist

Magento 2 besteht aus tausenden Dateien, Modulen und Konfigurationsebenen. Kleinste Unterschiede zwischen Umgebungen können dazu führen, dass ein Shop lokal funktioniert, aber auf Staging oder Live plötzlich Fehler ausgibt.

Ein professionelles Deployment sorgt für:

Konsistenz: Jede Umgebung baut aus dem gleichen Stand des Codes und der Abhängigkeiten.
Reproduzierbarkeit: Ein Release kann jederzeit erneut ausgerollt werden, ohne Überraschungen.
Nachvollziehbarkeit: Jede Änderung ist versioniert und dokumentiert.
Sicherheit: Keine sensiblen Zugangsdaten im Code, keine manuellen Eingriffe auf Live-Systemen.

Gerade für Freelancer, die an mehreren Projekten gleichzeitig arbeiten, ist das entscheidend. Ein klarer Prozess spart Stunden an Fehlersuche und macht dich professioneller in der Kundenkommunikation.

2. Git als Fundament jedes Deployments

Der Ausgangspunkt jedes modernen Magento Deployment ist ein Git-Repository. Es ist das Herz deines Projekts und bildet die Basis für alle Umgebungen.

Ein typischer Aufbau besteht aus drei Hauptzweigen:

main oder master: enthält den stabilen, live-tauglichen Code
develop: für Integrationstests und Feature-Zusammenführungen
feature/-Branches: für einzelne Aufgaben oder Tickets

Sobald ein Feature fertig ist, wird es über einen Merge Request oder Pull Request in den Develop-Branch integriert. Nach erfolgreichem Test auf Staging erfolgt der Merge in Main und anschließend das Live-Deployment.

Tipp: Committe niemals automatisch generierte Dateien wie pub/static, var, generated, .env oder vendor. Diese gehören in .gitignore. Der Code sollte immer aus dem Repository und dem Composer-Build entstehen.

3. Composer als Abhängigkeitsmanager

Composer ist für Magento 2 nicht nur ein Paketmanager, sondern Teil des Deployments selbst.
Ein häufiger Fehler ist, Abhängigkeiten lokal zu installieren und dann einfach hochzuladen. Besser ist es, den composer.lock ins Repository zu committen und alle Builds per Composer auszuführen.

Best Practice:

composer install --no-dev --optimize-autoloader

Dadurch wird sichergestellt, dass auf Staging und Live exakt dieselben Versionen aller Module und Libraries installiert werden.

Wenn du mehrere Projekte verwaltest, solltest du außerdem Composer Auth Credentials (z. B. für repo.magento.com oder private Repos) in der auth.json außerhalb des Projekts hinterlegen, damit sie nicht versehentlich im Git landen.

4. Environments klar trennen

Ein häufiger Stolperstein bei Freelancern ist die fehlende Trennung von Konfigurationen zwischen Local, Staging und Live.
Magento bringt dafür mit app/etc/env.php und app/etc/config.php bereits zwei saubere Ebenen mit.

env.php enthält alle sensiblen, umgebungsspezifischen Daten (z. B. DB, Redis, E-Mail, API Keys).
config.php enthält alle globalen Magento-Einstellungen, die im Git versioniert werden.

Auf Staging und Live sollten keine Änderungen direkt über das Admin Panel erfolgen, wenn diese Einstellungen in der config.php liegen. Das führt sonst zu Konflikten beim nächsten Deployment. Änderungen gehören in die lokale app/etc/config.php und werden über Git deployed.

5. Staging-System als Sicherheitsnetz

Ein separates Staging-System ist kein Luxus, sondern Pflicht.
Hier testest du neue Features, Composer-Updates, Caches und Datenbankänderungen unter realen Bedingungen, ohne den Live-Shop zu gefährden.

Der Workflow sieht so aus:

Merge des Feature-Branches in develop
Automatisches Deployment auf Staging
Funktionstests durch dich oder den Kunden
Merge in main nach Freigabe
Deployment auf Live

Wenn du viele Projekte betreust, lohnt sich die Einrichtung eines automatisierten Deployers, etwa mit GitLab CI, Bitbucket Pipelines, GitHub Actions oder einem einfachen Deployer-Script.

6. Automatisierung mit Deployer oder GitLab CI

Ein Deployment sollte so wenig manuell wie möglich ablaufen. Schon ein einziger vergessener Cache-Flush oder falscher File-Permission kann einen Shop lahmlegen.

Ein Beispiel für ein Deployment mit Deployer:

host('staging.example.com')
    ->set('deploy_path', '/var/www/staging')
    ->set('branch', 'develop');

task('deploy', [
    'deploy:prepare',
    'deploy:vendors',
    'magento:setup:upgrade',
    'magento:setup:di:compile',
    'magento:static:content:deploy',
    'magento:cache:flush',
]);

Deployer verbindet sich per SSH, zieht den Code aus Git, installiert Composer-Abhängigkeiten, kompiliert den Code und aktiviert anschließend den neuen Release-Ordner. Das garantiert, dass das System während des Deployments nie offline ist.

7. Caching und Build-Schritte richtig platzieren

Bei Magento 2 ist der Cache ein wichtiger Teil des Deployments.
Typische Befehle, die im CI/CD-Workflow automatisch ausgeführt werden sollten:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Diese Schritte sorgen dafür, dass nach jedem Release ein frischer Build entsteht, ohne alte statische Inhalte oder inkompatible Klassenreste. Besonders wichtig ist, dass setup:static-content:deploy nicht auf Live während der Geschäftszeiten ausgeführt wird.
Am besten erzeugst du die statischen Inhalte vorab auf dem Build-Server und kopierst sie in den Release-Ordner.

8. Datenbank und Media-Daten synchronisieren

Ein professionelles Deployment betrifft nicht nur den Code, sondern auch Datenbank und Medien.
Gerade bei größeren Projekten empfiehlt sich ein automatisiertes Sync-Script:

Datenbank-Dump von Live zu Staging (z. B. via mysqldump)
Replace-Skript für Domainnamen in der SQL-Datei
rsync oder S3-Sync für pub/media

Dabei gilt: Niemals Staging zurück auf Live importieren. Nur in eine Richtung, um versehentliche Datenverluste (z. B. Bestellungen oder Kundenkonten) zu vermeiden.

9. Deployment-Checkliste für Freelancer

Vor jedem Deployment sollten folgende Punkte abgehakt werden:

Branch in Git sauber gemergt
composer.lock aktuell
config.php committed
env.php auf Zielsystem geprüft
Cache, DI und Static Deploy vorbereitet
DB-Backup vorhanden
Tests auf Staging erfolgreich
Wartungsmodus aktiviert
Deployment-Script ausgeführt
Wartungsmodus deaktiviert

Diese Routine sichert nicht nur technische Stabilität, sondern auch Professionalität gegenüber Kunden. Ein strukturierter Ablauf zeigt, dass du Prozesse im Griff hast und vermeidet hektisches Troubleshooting am Freitagabend.

10. Fazit

Ein durchdachtes Magento Deployment ist keine Raketenwissenschaft, sondern das Ergebnis klarer Strukturen.
Wenn du Git als zentrale Quelle nutzt, Composer konsequent einsetzt, Environments sauber trennst und dein Deployment automatisierst, hast du bereits den gleichen Standard wie große Agenturen – nur mit weniger Overhead.

Als Freelancer bringt dir das vor allem drei Vorteile:

Du sparst Zeit bei wiederkehrenden Aufgaben.
Du vermeidest Fehler, die deinen Ruf gefährden.
Du wirkst in Kundenprojekten deutlich professioneller.

Wer den eigenen Prozess einmal richtig aufsetzt, profitiert langfristig von Stabilität, Kontrolle und Vertrauen.

Du suchst Unterstützung beim Aufbau eines stabilen Magento Deployment-Prozesses oder willst deine Staging-Umgebung automatisieren?
Dann melde dich bei mir auf Mage-Smith.com – ich helfe dir, deinen Workflow auf Agentur-Niveau zu bringen

MageSmith Blog