DDEV mit Image-Proxy h2non/imaginary einrichten – Anleitung für Entwickler

Die Integration eines Image-Proxies in lokale Entwicklungsumgebungen wie DDEV kann die Performance und Flexibilität von Webanwendungen deutlich verbessern. Besonders bei Projekten mit dynamischen Bildinhalten bietet der Open-Source-Proxy h2non/imaginary eine elegante Lösung. Mit wenigen Schritten lässt sich der Dienst in DDEV einbinden, um Bilder direkt im Container zu verarbeiten – ohne zusätzliche PHP-Module oder externe Abhängigkeiten.

Warum einen Image-Proxy in DDEV nutzen?

Moderne Webanwendungen wie Content-Management-Systeme (CMS) oder E-Commerce-Plattformen verarbeiten häufig große Mengen an Bilddateien. Ohne Optimierung können diese Dateien die Ladezeiten negativ beeinflussen und die Serverlast erhöhen. Hier setzt h2non/imaginary an: Der Proxy ermöglicht das dynamische Skalieren, Zuschneiden und Konvertieren von Bildern zur Laufzeit.

Die Vorteile liegen auf der Hand:

• Schnellere Ladezeiten: Bilder werden erst bei Bedarf angepasst, nicht beim Hochladen.
• Reduzierte Serverlast: Keine manuelle Bildoptimierung nötig.
• Flexible Anpassungen: Formatänderungen oder Größenanpassungen per URL-Parameter.
• Lokale Entwicklungsumgebung: Ideal für DDEV-Nutzer, die reale Produktionsbedingungen simulieren möchten.

Schritt-für-Schritt: h2non/imaginary in DDEV integrieren

Um den Image-Proxy in DDEV einzubinden, erstellen Sie zunächst eine spezielle Docker-Compose-Konfigurationsdatei. Diese Datei definiert den Dienst und bindet ihn an Ihre DDEV-Projektumgebung an.

Erstellen Sie die Datei .ddev/docker-compose.imaginary.yaml und fügen Sie folgenden Inhalt ein:

services:
  imaginary:
    image: h2non/imaginary:latest
    container_name: "ddev-${DDEV_PROJECT}-imaginary"
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    expose:
      - "9000"
    command: ["-enable-url-source"]
    restart: "no"
    environment:
      - VIRTUAL_HOST=${DDEV_HOSTNAME}
      - HTTP_EXPOSE=7000:9000
      - HTTPS_EXPOSE=7001:9000

Wichtige Konfigurationen im Detail

• `image`: Nutzt das offizielle Image von h2non/imaginary in der neuesten Version.
• `container_name`: Erstellt einen eindeutigen Containernamen basierend auf Ihrem DDEV-Projekt.
• `expose`: Öffnet den Port 9000 des Containers für die interne Kommunikation.
• `command`: Aktiviert die URL-basierte Bildverarbeitung mit der Option -enable-url-source.
• `environment`:
• `VIRTUAL_HOST`: Bindet den Proxy an die DDEV-Hostname-Konfiguration.
• `HTTP_EXPOSE` und `HTTPS_EXPOSE`: Leiten die Ports 7000 (HTTP) und 7001 (HTTPS) auf den Container-Port 9000 weiter.

Bilder im Projekt korrekt referenzieren

Nach der Einrichtung des Proxies müssen Sie sicherstellen, dass Ihre Anwendung die Bilder nicht direkt aus dem CMS oder dem Dateisystem lädt, sondern über den Proxy.

Angenommen, Ihre Anwendung nutzt Drupal, sollten Sie die Bild-URLs entsprechend anpassen. Statt einer direkten Referenz wie

nutzen Sie den Proxy-Endpunkt:

Beispiel für Drupal

In Drupal können Sie die Funktion image_style_url() oder ein Custom-Modul verwenden, um die URLs dynamisch anzupassen. Alternativ können Sie eine .htaccess-Regel oder ein Nginx-Konfigurationstemplate in DDEV anpassen, um die Anfragen umzuleiten.

Fehlerbehebung und Optimierungstipps

Sollte der Proxy nicht wie erwartet funktionieren, überprüfen Sie folgende Punkte:

• Port-Konflikte: Stellen Sie sicher, dass die Ports 7000 und 7001 in Ihrer DDEV-Konfiguration nicht bereits belegt sind.
• Hostname-Konfiguration: Der VIRTUAL_HOST muss mit dem in Ihrer config.yaml definierten Hostnamen übereinstimmen.
• Bild-URLs: Vergewissern Sie sich, dass die URLs korrekt formatiert sind und der Proxy Zugriff auf die Bilddateien hat.

Falls Sie persistente Daten benötigen, können Sie ein Volume für den Container einrichten. Fügen Sie hierfür die folgende Zeile in die docker-compose.imaginary.yaml ein:

volumes:
  - "imaginary-data:/data"

Fazit: Image-Proxy für lokale Entwicklung nutzen

Die Integration von h2non/imaginary in DDEV ist eine effiziente Methode, um Bildverarbeitung in lokalen Entwicklungsumgebungen zu optimieren. Durch die dynamische Anpassung von Bildern zur Laufzeit sparen Sie Ressourcen und beschleunigen die Entwicklung.

Für Teams, die regelmäßig mit Bildinhalten arbeiten, lohnt sich die Einrichtung dieses Proxies – besonders, wenn die Produktionsumgebung ähnliche Workflows nutzt. Mit der richtigen Konfiguration wird die lokale Entwicklung noch näher an die reale Serverumgebung angepasst, was zu konsistenteren Testergebnissen führt.