---
title: "Theme installieren"
description: "Ein eigenes Theme als ZIP-Datei im Plattform-Admin hochladen oder per Konsole einspielen – ohne Eingriff in Image oder Server"
---

Ein Theme ist ein Verzeichnis mit statischen Dateien (siehe [Themes](/anpassen/themes#aufbau)), verpackt als **ZIP-Datei**. Sie laden es im Plattform-Admin hoch; die Anwendung legt es im Speicher der Installation ab – dort, wo auch Logos, Bilder und Anhänge liegen (lokales Volume `uploads` oder S3-kompatibler Speicher). Image, Stack-Datei und Server bleiben unverändert, Updates lassen hochgeladene Themes unberührt.

Als Beispiel dient im Folgenden das [Beispiel-Theme](/downloads/beispiel-theme.zip) mit dem Schlüssel `beispiel` – es lässt sich unverändert hochladen.

## Im Plattform-Admin hochladen

1. Als Plattform-Admin anmelden und **Plattform-Admin → Darstellung** (`/admin/appearance`) öffnen.
2. Unter **Template hochladen** die ZIP-Datei wählen und **Template hochladen** klicken. Das Feld **Schlüssel** bleibt leer – dann gilt `key` aus `theme.json`. Ein eingetragener Schlüssel ersetzt ihn (praktisch, um eine Kopie unter neuem Namen anzulegen).
3. Das Theme erscheint in der Liste mit dem Hinweis **Hochgeladen**. Mit **Verwenden** wird es für alle Besucher aktiv.

Die Anwendung prüft das Paket vollständig, bevor sie etwas speichert. Ist etwas falsch, bleibt alles beim Alten und die Seite zeigt **alle** gefundenen Fehler mit Datei und – bei CSS – Zeile, z. B. `theme.css, Zeile 12: url(https://fonts.example/a.woff2) verweist auf eine fremde oder absolute Adresse`. Die Regeln stehen unter [Anforderungen an das Paket](#anforderungen-an-das-paket).

<Note>
Der Schlüssel eines mitgelieferten Themes (`quicktribe`, `mitternacht`, `arena`, `verein`, `schuetzen`, `reiterhof`, `parcours`, `business`) lässt sich nicht überschreiben. Wer eines davon abwandeln möchte, lädt mit **Kopie herunterladen** eine Fassung mit eigenem Schlüssel (`mein-mitternacht`) herunter, ändert sie und lädt sie wieder hoch.
</Note>

## Neue Fassung, vorige Fassung, löschen

- **Neue Fassung:** Eine ZIP-Datei mit demselben Schlüssel ersetzt das vorhandene Theme. Ist es aktiv, sehen Besucher die neue Fassung beim nächsten Seitenaufruf – ohne Neustart und ohne Cache-Probleme, weil sich die Adressen aller Theme-Dateien mit dem Inhalt ändern.
- **Vorige Fassung wiederherstellen:** Die letzten fünf Fassungen bleiben als Archiv erhalten. Die Schaltfläche stellt die jüngste davon wieder her; die ersetzte Fassung wandert dabei ins Archiv. Zweimal hintereinander geklickt ist also wieder die Ausgangsfassung aktiv.
- **Herunterladen:** liefert das Theme als ZIP-Datei – derselbe Inhalt lässt sich auf einer anderen Installation wieder hochladen. Bei mitgelieferten Themes heißt die Schaltfläche **Kopie herunterladen** (Schlüssel `mein-<name>`, Name mit „(Kopie)“).
- **Löschen:** entfernt das Theme samt Archiv. War es aktiv, gilt sofort wieder das Standard-Theme `quicktribe`; die Seite weist darauf hin.

Alle Aktionen stehen im Protokoll des Plattform-Admins (`platform.appearance.theme_uploaded`, `…theme_restored`, `…theme_deleted`).

## Per Konsole

Für Automatisierung, Installationen ohne Browserzugang oder wenn der Plattform-Admin gerade nicht erreichbar ist, gibt es dieselben Funktionen als Konsolenbefehle mit denselben Prüfregeln. Die ZIP-Datei muss dafür im Container liegen:

```bash
docker compose cp beispiel-theme.zip app:/tmp/beispiel-theme.zip
docker compose exec app php bin/console app:theme:validate /tmp/beispiel-theme.zip            # nur prüfen
docker compose exec app php bin/console app:theme:import /tmp/beispiel-theme.zip --activate   # hochladen und aktivieren
docker compose exec app php bin/console app:theme:list                                        # alle Themes, * = aktiv
docker compose exec app php bin/console app:theme:export beispiel /tmp/beispiel.zip           # als ZIP speichern
```

| Befehl | Wirkung |
| --- | --- |
| `app:theme:validate <zip> [--key=<name>]` | prüft ein Paket, ohne es zu speichern; Exit-Code 1 bei Fehlern |
| `app:theme:import <zip> [--key=<name>] [--activate]` | wie der Upload im Plattform-Admin; `--activate` wählt das Theme aus (nicht möglich, solange `APP_TEMPLATE` gesetzt ist) |
| `app:theme:list` | mitgelieferte und hochgeladene Themes mit Version, Upload-Zeitpunkt und Zahl der archivierten Fassungen |
| `app:theme:export <name> <ziel.zip> [--as=<name>]` | Theme als ZIP; mitgelieferte als Kopie mit Schlüssel `mein-<name>` |

Alle Optionen stehen in der Referenz unter [Betrieb → Konsole](/betrieb#konsole), Beispiele für den Alltag im Handbuch unter [Konsole](/handbuch/plattform-admin/konsole). Bei Portainer und Coolify laufen die Befehle in der Konsole des Containers `app`; die Datei kommt z. B. per `docker cp` auf dem Docker-Host in den Container. Bei einer [Installation ohne Docker](/installation/webserver) heißt der Aufruf `runuser -u www-data -- php bin/console app:theme:import …` im Verzeichnis `current/`.

Der Benutzer, unter dem der Befehl läuft, spielt seit 1.7.3 keine Rolle: Läuft er als `root` (Standard bei `docker compose exec`), übergibt `app:theme:import` – wie jeder Konsolenbefehl, der in den lokalen Speicher schreibt – die geschriebenen Dateien und Verzeichnisse an den Eigentümer des Speicherverzeichnisses (im Image `www-data`), damit der Webserver sie ausliefern kann. Bei S3-kompatiblem Speicher entfällt das.

## Anforderungen an das Paket

| Regel | Grenze bzw. Erlaubtes |
| --- | --- |
| Paket | ZIP-Datei bis 10 MB, höchstens 200 Dateien, entpackt höchstens 30 MB |
| Aufbau | `theme.json` direkt in der ZIP-Datei oder in genau einem Ordner (so entsteht es beim Packen eines Verzeichnisses); Hilfsdateien wie `__MACOSX/` oder `.DS_Store` werden übergangen |
| Pfade | Buchstaben, Ziffern, `-`, `_`, `.`, höchstens ein Unterverzeichnis (`fonts/inter.woff2`); keine absoluten Pfade, kein `..`, keine symbolischen Links, keine versteckten Dateien |
| Endungen | `json`, `css`, `woff2`, `woff`, `png`, `webp`, `jpg`/`jpeg`, `svg`, `txt`, `md` (kleingeschrieben); der Inhalt muss zur Endung passen |
| `theme.json` | gültiges JSON mit den Feldern aus [theme.json](/anpassen/themes#theme-json); jede genannte Datei liegt im Paket |
| CSS | kein `@import`, kein `expression()`, kein `javascript:`, keine Backslash-Escapes außerhalb von Zeichenketten; `url()` nur auf Dateien im Paket (relativ zur CSS-Datei) oder als `data:`-Adresse für Bilder und Schriften |
| SVG | kein `<script>`, keine Ereignis-Attribute (`onload` …), kein `<foreignObject>`, keine Verweise auf fremde Adressen, kein `DOCTYPE` |

## Hinweis für Entwickler: Theme im Image

Mitgelieferte Themes liegen im Image unter `public/themes/<key>/` und werden vom Webserver statisch ausgeliefert. Für die Arbeit an der Anwendung selbst oder für ein eigenes, abgeleitetes Image kann ein Theme dort liegen (`COPY themes/meine-marke /var/www/public/themes/meine-marke`); sein Schlüssel ist dann wie bei den mitgelieferten reserviert, und es erscheint auf jeder Installation mit diesem Image in der Auswahl. Für den Betrieb ist der Upload der vorgesehene Weg – er übersteht Updates ohne Neubau und braucht keinen Zugriff auf den Server.
