Laravel-App auf IONOS hosten: Schritt-für-Schritt-Anleitung ohne Root-Zugriff

Wichtig vorab: IONOS stellt auf Shared-Hosting-Paketen mehrere PHP-CLI-Versionen parallel bereit, von php7.4-cli bis php8.5-cli. Alle Befehle in dieser Anleitung (Composer, Artisan) sollten deshalb immer mit der expliziten Version aufgerufen werden, zum Beispiel php8.3-cli statt einfach php. Wer das übersieht, landet schnell bei einer veralteten Standardversion, die nicht zu den Anforderungen von Laravel passt.

SSH-Zugangsdaten im IONOS-Panel finden

Im IONOS-Kundenkonto unter Hosting > SFTP & SSH findet man die Zugangsdaten für den SSH-Zugriff. Wichtig dabei: Nur der Hauptbenutzer eines Hosting-Pakets hat SSH-Zugriff, zusätzlich angelegte FTP-Benutzer können sich nicht per SSH anmelden.

Für den Login empfiehlt sich ein SSH-Key statt Passwort: den eigenen Public Key vorab per ssh-copy-id oder manuell in der Datei authorized_keys im .ssh-Verzeichnis auf dem Server hinterlegen. Das erspart bei jedem Deploy die Passworteingabe.

Per SSH mit dem Server verbinden

Verbindung herstellen mit:

ssh benutzername@servername

Nach der Anmeldung landet man im Home-Verzeichnis des Hauptbenutzers.

Projekt per Git auf den Server holen

In den gewünschten Projektordner wechseln (meist htdocs oder ein Unterordner davon) und das Repository klonen:

git clone <repository-url> projektordner

Bei einem bestehenden Projekt genügt später ein einfaches git pull, um den neuesten Stand zu holen.

Composer ohne Root installieren

Viele Hoster wie IONOS geben keinen Root-Zugriff und keinen Paketmanager, apt install composer fällt also flach. Trotzdem lässt sich Composer problemlos einrichten.

composer.phar herunterladen

mkdir -p ~/bin
cd ~/bin
curl -sS https://getcomposer.org/installer | php8.3-cli
mv composer.phar ~/bin/composer.phar

Wrapper-Skript anlegen

Da composer.phar selbst kein Shebang für die richtige PHP-Version garantiert, lohnt sich ein kleiner Wrapper unter ~/bin/composer mit folgendem Inhalt:

#!/bin/sh
exec php8.3-cli $HOME/bin/composer.phar "$@"

Danach ausführbar machen:

chmod +x ~/bin/composer

PATH erweitern

Damit composer überall funktioniert, ~/bin in der .bashrc bzw. .bash_profile in den PATH aufnehmen:

export PATH="$HOME/bin:$PATH"

Test, ob alles funktioniert:

composer --version

Sollte anschließend die installierte Composer- und PHP-Version anzeigen, ganz ohne Root-Rechte und mit expliziter PHP-Version.

Composer-Abhängigkeiten installieren

In den Laravel-Projektordner wechseln und die Abhängigkeiten für Produktion installieren:

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

Die Flags sorgen dafür, dass Dev-Abhängigkeiten wegfallen und der Autoloader für Produktion optimiert wird.

Die .env-Datei einrichten

Vorlage kopieren und Werte anpassen:

cp .env.example .env

Datenbankzugangsdaten (aus dem IONOS-Panel), APP_URL und die Produktionswerte eintragen:

APP_ENV=production
APP_DEBUG=false

Dazu DB_HOST, DB_DATABASE, DB_USERNAME und DB_PASSWORD passend zum IONOS-Datenbankzugang.

Hinweis: Die .env gehört nicht ins Git-Repository. Sie bleibt dauerhaft auf dem Server und wird bei jedem neuen Deploy nicht überschrieben, da sie in der .gitignore ausgeschlossen ist.

Laravel initialisieren

Mit der zuvor gewählten PHP-CLI-Version nacheinander ausführen:

php8.3-cli artisan key:generate
php8.3-cli artisan storage:link
php8.3-cli artisan migrate --force
php8.3-cli artisan optimize

storage:link erzeugt den Symlink von public/storage zu storage/app/public, ohne ihn liefern hochgeladene Dateien einen 404. Das --force bei migrate ist nötig, weil Artisan im Produktionsmodus sonst nach einer interaktiven Bestätigung fragt, die auf einer nicht-interaktiven SSH-Sitzung fehlschlägt.

Verzeichnis-Rechte und Document Root setzen

storage/ und bootstrap/cache/ müssen für den Webserver beschreibbar sein:

chmod -R 775 storage bootstrap/cache

Fehlt das, quittiert Laravel jede Anfrage mit einem 500er.

Zusätzlich zeigt der Webspace-Root bei IONOS standardmäßig nicht auf laravel/public, sondern auf das Hauptverzeichnis. Im IONOS-Panel lässt sich unter den Domain-Einstellungen ein alternatives Verzeichnis als Document Root hinterlegen, dort trägt man den public-Ordner des Projekts ein. Geht das nicht, hilft ersatzweise eine .htaccess im Webspace-Root, die auf laravel/public/index.php verweist.

Frontend-Assets: npm-Build ins Repository aufnehmen

Auf IONOS-Shared-Hosting steht kein Node.js/npm zur Verfügung, ein npm run build auf dem Server ist also nicht möglich. Die Lösung: /public/build aus der .gitignore entfernen und die gebauten Assets lokal erzeugen und mitcommiten:

npm run build
git add public/build
git commit -m "Build assets"
git push

Bei jedem Deploy muss dieser Schritt vor dem git pull auf dem Server wiederholt werden, sonst laufen Frontend und Backend auseinander.

Scheduler und Queues ohne Supervisor betreiben

Da auf Shared Hosting kein Supervisor läuft, muss der Laravel-Scheduler über einen IONOS-Cronjob angestoßen werden, im Panel unter Cronjobs einen Minuten-Job anlegen:

* * * * * php8.3-cli /pfad/zu/projekt/artisan schedule:run >> /dev/null 2>&1

Für Queues gilt dasselbe Problem: queue:work als Dauerprozess ist ohne Root/Supervisor nicht sauber realisierbar. Für die meisten Projekte reicht folgender Eintrag in der .env, wodurch Jobs synchron im Request abgearbeitet werden:

QUEUE_CONNECTION=sync

Braucht man echte Warteschlangen, lässt sich alternativ ein eigener Cronjob einrichten:

php8.3-cli artisan queue:work --stop-when-empty

Document Root auf /public setzen

Die Domain muss im IONOS-Panel auf den public-Ordner des Projekts zeigen, nicht auf das Projekt-Root. Bei den Domain-Einstellungen das Verzeichnis explizit auf /public setzen, sonst landet man auf Laravels Projektstruktur statt auf dem Front-Controller.

Troubleshooting: 404 oder 503 auf Unterseiten

Springt nur die Startseite an, während alle anderen Routen mit 404 oder 503 antworten, liegt es meist an der Rewrite-Konfiguration von IONOS, die vom Standard abweicht.

In Laravels public/.htaccess innerhalb von <IfModule mod_rewrite.c>, direkt nach dem Options -MultiViews -Indexes-Block und noch vor den restlichen RewriteCond-Regeln, ergänzen:

RewriteEngine On
RewriteBase /
Options +FollowSymLinks

IONOS Standard-Rewrite-Base weicht sonst vom Projektpfad ab, wodurch nur die Startseite (index.php direkt) funktioniert, alle anderen Laravel-Routen aber ins Leere laufen.

Fazit

Laravel auf IONOS-Shared-Hosting zum Laufen zu bringen ist kein Hexenwerk, erfordert aber ein paar Kniffe, die auf klassischem Root-Server-Hosting keine Rolle spielen: explizite PHP-CLI-Versionen, ein Composer-Wrapper ohne Root, korrekt gesetzte Verzeichnis-Rechte und Document Root sowie Ersatzlösungen über Cronjobs statt Supervisor für Scheduler und Queues. Wer diese Punkte einmal sauber eingerichtet hat, kann künftige Deploys mit wenigen Befehlen wiederholen.