Lokale Einrichtung

Betreiben Sie eine vollständige fepli-Instanz auf Ihrem eigenen Rechner, mit demselben Image wie im Produktivbetrieb. Nutzen Sie sie, um fepli auszuprobieren, Kolleg:innen zu schulen oder ein Update zu proben. Nichts verlässt Ihren Rechner: Jede E-Mail landet in einem Mail-Catcher.

Was Sie brauchen

• Docker Desktop oder Docker Engine mit dem Compose-Plugin, mit etwa 4 GB Arbeitsspeicher für die Container.
• Den Benutzernamen und das Token, die fepli Ihnen für die Image-Registry gegeben hat.
• Chrome, Edge oder Firefox. Sie leiten jeden Namen *.localhost an Ihren eigenen Rechner um, was diese Einrichtung für die Domains der Mandanten nutzt. In anderen Browsern tragen Sie 127.0.0.1 elmsbrueck.localhost in Ihre hosts-Datei ein.

1. Bei der Registry anmelden

docker login ghcr.io --username <your user name>

Fügen Sie das Token ein, wenn Docker nach dem Passwort fragt. Docker merkt sich die Anmeldung.

2. Die Instanz beschreiben

Legen Sie einen Ordner an, z. B. fepli, mit zwei Dateien. Die erste beschreibt die Container:

name: fepli

x-fepli: &fepli
  image: ghcr.io/ferienpass/app:general-latest
  platform: linux/amd64
  env_file: fepli.env
  restart: unless-stopped
  depends_on:
    mariadb:
      condition: service_healthy
    redis:
      condition: service_started
  volumes:
    - files:/app/files
    - storage:/app/storage
    - images:/app/contao-assets/images
    - deferred-images:/app/var/deferred-images

services:
  web:
    <<: *fepli
    ports:
      - '127.0.0.1:8080:80'
    # Der Port öffnet sich, sobald die Datenbank migriert ist; Worker und Cron warten darauf.
    healthcheck:
      test: ['CMD', 'php', '-r', 'exit(@fsockopen("127.0.0.1", (int) (getenv("PORT") ?: 80)) ? 0 : 1);']
      interval: 10s
      start_period: 10m

  worker:
    <<: *fepli
    environment:
      IS_WORKER: '1'
    depends_on:
      web:
        condition: service_healthy

  cron:
    <<: *fepli
    command: ['while true; do php bin/console contao:cron; sleep 60; done']
    depends_on:
      web:
        condition: service_healthy

  mariadb:
    image: mariadb:12.3
    restart: unless-stopped
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    environment:
      MARIADB_ROOT_PASSWORD: root
      MARIADB_DATABASE: fepli
      MARIADB_USER: fepli
      MARIADB_PASSWORD: fepli
    healthcheck:
      test: ['CMD', 'healthcheck.sh', '--connect', '--innodb_initialized']
      interval: 10s
      retries: 10
    volumes:
      - db:/var/lib/mysql

  redis:
    image: redis:8
    restart: unless-stopped
    command: ['redis-server', '--appendonly', 'yes', '--maxmemory-policy', 'noeviction']
    volumes:
      - redis:/data

  mailpit:
    image: axllent/mailpit
    ports:
      - '127.0.0.1:8025:8025'

volumes:
  db:
  redis:
  files:
  storage:
  images:
  deferred-images:

Diese Einrichtung läuft ohne Varnish. Auf dem eigenen Rechner ist das am unkompliziertesten. Ergänzen Sie es, wenn Sie es ausprobieren möchten.

Web-, Worker- und Cron-Container sind dasselbe Image mit denselben Einstellungen. Nur ihre Aufgabe unterscheidet sich: Der Worker erhält IS_WORKER=1, und der Cron führt die zeitgesteuerten Aufgaben einmal pro Minute aus. Die Volumes bewahren die hochgeladenen Dateien auf, wenn Sie die Container neu erstellen. Web und Worker teilen sie, weil der Worker die Exporte schreibt, die der Web-Container ausliefert. Die veröffentlichten Ports lauschen nur auf 127.0.0.1, deshalb erreichen andere Rechner in Ihrem Netz die Instanz nicht.

Die zweite Datei enthält die Konfiguration. Sie beginnt mit zwei Schlüsseln, die nur zu dieser Instanz gehören. Das Image führt fepli als prod aus, auch auf Ihrem Rechner, und dort verweigert fepli Schlüssel, die leer sind oder von fepli veröffentlicht wurden, darunter die, die frühere Versionen dieser Seite verwendet haben. Erzeugen Sie die Schlüssel:

openssl rand -hex 32      # APP_SECRET
openssl rand -base64 32   # INTEGRATIONS_ENCRYPTION_KEY

Tragen Sie sie in die Datei ein:

# openssl rand -hex 32
APP_SECRET=9f1c…
# openssl rand -base64 32
INTEGRATIONS_ENCRYPTION_KEY=Qm3v…

DATABASE_URL=mysql://fepli:fepli@mariadb:3306/fepli
DATABASE_SERVER_VERSION=mariadb-12.3.0

REDIS_URL=redis://redis:6379/1
LOCK_DSN=redis://redis:6379/2
SESSION_DSN=redis://redis:6379/3
MESSENGER_TRANSPORT_DSN=redis://redis:6379/messages

# Leer: kein Varnish
VARNISH_HOST=

TRUSTED_HOSTS='^(localhost|[a-z0-9-]+\.localhost)$'
APP_BASE_URL=http://localhost:8080
FEPLI_PLATFORM_HOST=localhost

MAILER_DSN=smtp://mailpit:1025
ADMIN_EMAIL=ferienpass@example.fepli.eu

Damit ist localhost die Plattform-Konsole, und jeder Name *.localhost kann ein Mandant sein. So können Sie die Varianten mit einem Mandanten und mit mehreren Mandanten ausprobieren.

3. Starten

docker compose up -d

Beim ersten Start lädt Docker die Images herunter, was einige Minuten dauert. Danach legt der Web-Container die Tabellen von fepli an, bevor er antwortet, und Worker und Cron starten, sobald er antwortet. Bei jedem Update geschieht dasselbe: Der Web-Container ändert nur, was die neue Version braucht. docker compose ps zeigt, ob alles läuft; docker compose logs -f web zeigt, was der Web-Container tut.

4. Mandanten und Admin anlegen

Legen Sie den Mandanten Elmsbrück an, erreichbar unter elmsbrueck.localhost, und seinen ersten Admin:

docker compose exec web php bin/console ferienpass:tenant:create elmsbrueck "Ferienpass Elmsbrück" \
  --host=elmsbrueck.localhost

docker compose exec web php bin/console ferienpass:user:create anna.schmidt@example.fepli.eu \
  --tenant=elmsbrueck --firstname=Anna --lastname=Schmidt

Wählen Sie ein Passwort, wenn der Befehl danach fragt. Danach:

Elmsbrück hat noch keine Website: Geben Sie ihm eine Wurzelseite im CMS.

5. Die Plattform-Konsole ausprobieren

Für die Konsole legen Sie einen globalen Admin an und melden sich unter http://localhost:8080 an:

docker compose exec web php bin/console ferienpass:user:create you@example.org --global-admin

Dort sehen Sie Elmsbrück in der Liste der Mandanten, können in den Mandanten wechseln und weitere Mandanten anlegen, z. B. einen unter beispielhausen.localhost.

Varnish ergänzen

Um fepli so zu erleben, wie es mit Cache läuft, stellen Sie Varnish vor den Web-Container. Fügen Sie den Dienst in compose.yaml hinzu und verlegen Sie den Port von web auf ihn:

services:
  web:
    <<: *fepli
    # wie oben, aber ohne ports: Varnish ist jetzt der Zugang

  varnish:
    image: ghcr.io/ferienpass/varnish:latest
    restart: unless-stopped
    environment:
      VARNISH_STORAGE: malloc,256m
    ports:
      - '127.0.0.1:8080:80'
    depends_on:
      - web

Teilen Sie fepli in fepli.env mit, wo Varnish läuft:

VARNISH_HOST=varnish:80
VARNISH_BASE_URL=http://varnish

Führen Sie danach docker compose up -d aus. Die Adressen bleiben dieselben. Um zurückzukehren, entfernen Sie den Dienst wieder und leeren Sie VARNISH_HOST.

Anhalten, aktualisieren und neu beginnen

Wenn etwas nicht funktioniert

• Ein 400 für eine Domain: Sie passt nicht zu TRUSTED_HOSTS.
• Ein 404 für eine Domain: Kein Mandant beansprucht sie. Prüfen Sie die Domains mit ferienpass:tenant:list. Haben Sie die Domain mit Varnish geöffnet, bevor ein Mandant sie beansprucht hat, hält Varnish das 404 möglicherweise noch fest: Leeren Sie es mit docker compose exec web php bin/console app:flush-varnish --all-tenants.
• Eine Fehlerseite direkt nach dem Start: Der Web-Container legt noch die Tabellen an. Warten Sie, bis docker compose logs web Starting server zeigt. Bricht er stattdessen ab, nennt das Log davor den Grund.
• Jede Seite ist ein Fehler, und das Log sagt This installation does not run in the "prod" environment until its secrets are its own: APP_SECRET oder INTEGRATIONS_ENCRYPTION_KEY in fepli.env ist leer oder ein veröffentlichter Wert, etwa einer von früheren Versionen dieser Seite. Die Meldung nennt, welcher. Erzeugen Sie eigene Werte und führen Sie dann docker compose up -d aus. Zugangsdaten, die im Admin-Panel unter dem alten INTEGRATIONS_ENCRYPTION_KEY gespeichert wurden, müssen Sie erneut eingeben.
• In Mailpit kommt keine E-Mail an: Der Worker verschickt sie. Prüfen Sie mit docker compose logs worker, ob er läuft.
• Auf einem Mac mit Apple Silicon ist es sehr langsam: Das Image ist für x86 gebaut und läuft per Emulation. Schalten Sie in den Einstellungen von Docker Desktop „Use Rosetta for x86/amd64 emulation“ ein.