diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index e13ff301..586b75ad 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -89,22 +89,22 @@ jobs: id-token: write steps: - uses: actions/checkout@v5 - - name: "Set up Python 3.12" + - name: "Set up Python 3.x" uses: actions/setup-python@v5 with: - python-version: "3.12" + python-version: "3.x" - name: "Install requirements" run: "python3 -m pip install -r requirements.txt" working-directory: "docs" - name: "Build documentation" - run: "python3 -m mkdocs build" + run: "zensical build --clean" working-directory: "docs" - name: "Setup Pages" uses: actions/configure-pages@v5 - - name: Upload artifact + - name: "Upload artifact" uses: actions/upload-pages-artifact@v3 with: path: "docs/site" - - name: Deploy to GitHub Pages + - name: "Deploy to GitHub Pages" id: deployment uses: actions/deploy-pages@v4 diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 977cc976..15df5328 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -12,13 +12,13 @@ jobs: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v5 - - name: "Set up Python 3.12" + - name: "Set up Python 3.x" uses: actions/setup-python@v5 with: - python-version: "3.12" + python-version: "3.x" - name: "Install requirements" run: "python3 -m pip install -r requirements.txt" working-directory: "docs" - name: "Build documentation" - run: "python3 -m mkdocs build" + run: "zensical build --clean" working-directory: "docs" diff --git a/README.md b/README.md index 8f184447..43cea2e3 100644 --- a/README.md +++ b/README.md @@ -6,20 +6,12 @@ ## Introduction -**turnierplan.NET** is mostly written in C# using [.NET](https://dotnet.microsoft.com/). This includes the core logic, the backend API and database connection as well as all publicly visible web pages. In addition, it serves the *turnierplan.NET portal*, the client application for authenticated users, based on the [Angular](https://angular.dev/) framework. Some screenshots can be seen in the [section at the end](#screenshots). +**turnierplan.NET** is mostly written in C# using [.NET](https://dotnet.microsoft.com/). This includes the core logic, the backend API and database connection as well as all publicly visible web pages. In addition, it serves the *turnierplan.NET portal*, the client application for authenticated users, based on the [Angular](https://angular.dev/) framework. -> [!NOTE] -> The user interface is currently only available in German 🇩🇪 - -## Installation - -If you want to install **turnierplan.NET** on your server, please visit the [Installation guide](https://docs.turnierplan.net/installation). +Visit the **turnierplan.NET** documentation using the following link: [docs.turnierplan.net](https://docs.turnierplan.net). If you want to install **turnierplan.NET** on your server, please visit the [Installation guide](https://docs.turnierplan.net/installation). -## Documentation - -Visit the **turnierplan.NET** documentation using the following link: [docs.turnierplan.net](https://docs.turnierplan.net) - -The documentation sources are located in the `docs` directory. See the [docs readme](docs/README.md) for further information on how to edit and build the documentation. +> [!NOTE] +> The user interface and documentation are currently only available in German 🇩🇪 ## Development diff --git a/docs/README.md b/docs/README.md index c8f9dfa2..ba869c23 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,16 +1,16 @@ ## turnierplan.NET · Documentation -This directory contains the source markdown files and mkdocs configuration for the publically available turnierplan.NET documentation: [https://docs.turnierplan.net](https://docs.turnierplan.net). +This directory contains the turnierplan.NET documentation. The content files use an extended markdown format and are build into static HTML using [zensical](https://zensical.org). The documentation is hosted at [docs.turnierplan.net](https://docs.turnierplan.net). -In order to build the documentation locally, you must first install Python and [mkdocs](https://www.mkdocs.org): +In order to build the documentation locally, you must first install Python and `zensical`: ``` pip install -r requirements.txt ``` -Next, you can either view the rendered documentation using the mkdocs-build-in server or you can generate the static website files: +Next, you can either view the rendered documentation using the zensical built-in server or you can generate the static website files: ``` -python3 -m mkdocs serve # starts a local web server on port 8000 -python3 -m mkdocs build # generates static web site artifacts into the 'site' directory +python3 -m zensical serve # starts a local web server on port 8000 +python3 -m zensical build # generates static web site artifacts into the 'site' directory ``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index b144ae2f..00000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,32 +0,0 @@ -site_name: "turnierplan.NET" -site_author: "turnierplan.NET" -site_url: "https://docs.turnierplan.net" -site_description: "The administrator and user documentation for turnierplan.NET" - -repo_url: "https://github.com/turnierplan-NET/turnierplan.NET" -edit_uri: "blob/main/docs/pages/" - -copyright: "Copyright © 2026 Elias Hörner" - -docs_dir: "pages" - -theme: - name: mkdocs - color_mode: auto - user_color_mode_toggle: true - nav_style: dark - navigation_depth: 4 - locale: en - -nav: - - Home: "index.md" - - Installation: "installation.md" - - About: - - Releases: "https://github.com/turnierplan-NET/turnierplan.NET/releases" - - License: "https://github.com/turnierplan-NET/turnierplan.NET/blob/main/LICENSE" - -extra_css: - - "assets/turnierplan.css" - -markdown_extensions: - - admonition: diff --git a/docs/pages/assets/turnierplan.css b/docs/pages/assets/turnierplan.css index ac947a92..ddc08d85 100644 --- a/docs/pages/assets/turnierplan.css +++ b/docs/pages/assets/turnierplan.css @@ -1,46 +1,11 @@ -/* - * Some style improvements for the footer - */ - -footer hr { - opacity: 0.2; -} - -footer p { - font-size: 0.8em; - margin-bottom: 0.3em; -} - -/* - * Remove the sidebar on the homepage, copied from the mkdocs.org documentation - * => https://github.com/mkdocs/mkdocs/blob/2862536793b3c67d9d83c33e0dd6d50a791928f8/docs/css/extra.css#L48 - */ - -body.homepage > div.container > div.row > div.col-md-3 { - display: none; -} - -body.homepage > div.container > div.row > div.col-md-9 { - margin-left: 0; - flex: 0 0 100%; - max-width: 100%; -} -/* - * Some additional style changes for the homepage - */ - -body.homepage h1 { - margin-top: 2em; - margin-bottom: 0.7em; - text-align: center; - font-weight: bold; -} - -body.homepage > div.container p:first-of-type { - text-align: center; +.md-copyright { + /* Decrease size of the footer text */ + font-size: 0.8em; } -body.homepage > div.container img:first-of-type { - padding: unset; - border: unset; +.md-content img { + /* Center images and add small shadow */ + display: block; + margin: 0 auto; + box-shadow: 0 0 3px rgba(0, 0, 0, 0.2); } diff --git a/docs/pages/configuration/index.md b/docs/pages/configuration/index.md new file mode 100644 index 00000000..f5ded4e8 --- /dev/null +++ b/docs/pages/configuration/index.md @@ -0,0 +1,122 @@ +--- +icon: lucide/wrench +--- + +# Konfiguration + +Unabhängig vom Deployment und der verwendeten Hardware/Server bietet turnierplan.NET zahlreiche Konfigurationsmöglichkeiten, welche nachfolgend näher beschrieben sind. + +## Erforderliche Einstellungen + +Für eine produktive Installation müssen die folgenden Umgebungsvariablen zwingend gesetzt sein: + +| Umgebungsvariable | Beschreibung | +|-------------------------------|--------------------------------------------------------------------| +| `Turnierplan__ApplicationUrl` | Die URL, welche für den Web-Zugriff auf den Server verwendet wird. | +| `Database__ConnectionString` | Connection-String für die PostgreSQL-Datenbank. | + +## Allgemeine Einstellungen + +Die folgenden Einstellungen können gesetzt werden, um das allgemeine Aussehen und Verhalten von turnierplan.NET zu konfigurieren: + +| Umgebungsvariable | Beschreibung | Standard | +|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| +| `Turnierplan__InstanceName` | Dieser Name wird in der Kopfzeile und Fußzeile von den öffentlichen Seiten angezeigt. Falls nicht spezifiert, wird der Text `turnierplan.NET` angezeigt. | - | +| `Turnierplan__LogoUrl` | Die URL für das Vereins-/Firmenlogo, welches in der Kopfzeile von öffentlichen Seiten angezeigt werden soll. Falls nicht spezifiert, wird das turnierplan.NET-Logo angezeigt. | - | +| `Turnierplan__ImprintUrl` | Die URL für den Verweis auf ein externes Impressum, welches bspw. auf Ihrer Vereins-/Firmenseite gehostet ist. | - | +| `Turnierplan__PrivacyUrl` | Die URL für den Verweis auf eine externe Datenschutz-Seite, welche bspw. auf Ihrer Vereins-/Firmenseite gehostet ist. | - | +| `Turnierplan__InitialUserName` | Der Benutzername für den initalen Administratorbenutzer. Sofern nicht angegeben, wird der Benutzername von der Anwendung vorgegeben und beim ersten Start in der Konsole ausgegeben. | - | +| `Turnierplan__InitialUserPassword` | Das Passwort für den initialen Administratorbenutzer. Sofern nicht angegeben, wird beim ersten Start der Anwendung ein zufälliges Passwort generiert und in der Konsole ausgegeben. | - | + +## Bilder-Uploads + +In der Weboberfläche können Bilddateien hochgeladen werden. Diese werden mit einer bestimmten Qualitätseinstellung in das `webp`-Format konvertiert und anschließend standardmäßig als Dateien in einem Container-Verzeichnis gespeichert. Das entsprechende Verzeichnis sollte [als Volume persistiert](http://localhost:8000/installation/#volume-mounts) werden. Folgende Einstellungen sind verfügbar: + +| Umgebungsvariable | Beschreibung | Standard | +|-----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------| +| `Turnierplan__ImageMaxSize` | Die maximale Dateigröße für Bild-Uploads in Bytes. Der Standard-Wert entspricht 8 MiB (8 · 1024 · 1024) | `8388608` | +| `Turnierplan__ImageQuality` | Die Qualitätseinstellung für Bild-Uploads. Ein Wert von `100` entspricht einer verlustfreien Komprimierung. | `80` | +| `ImageStorage__StoragePath` | Das Verzeichnis innerhalb vom Container, hochgeladene Bilder gespeichert werden. | `/var/turnierplan/images` | + +Alternativ können externe Services zum Speichern der Bilder konfiguriert werden. Dies hat den Vorteil, dass das Bereitstellen von Bilddateien keine CPU- und Netzwerkresourcen vom turnierplan.NET-Server beansprucht. Aktuell werden die folgenden externen Services unterstützt: + +- **AWS S3** (oder kompatibler Dienst) +- **Azure Blob Storage** + +!!! warning + Die nachfolgend vorgestellten Alternativen verwenden nicht zwangsläufig eine identische Verzeichnisstruktur zur Organisation der Dateien. Dadurch wird eine nachträgliche Umstellung ggf. erschwert! + +### AWS S3 + +Um Bilder in einem AWS S3 oder S3-kompatiblen Bucket zu speichern, müssen die folgenden Umgebungsvariablen gesetzt werden: + +| Umgebungsvariable | Beschreibung | +|---------------------------------|------------------------------------------------------------------| +| `ImageStorage__Type` | Muss `S3` sein. | +| `ImageStorage__RegionEndpoint` | Der Name der AWS-Region, bspw. `eu-central-1`. | +| `ImageStorage__ServiceUrl` | Die Service-URL, falls ein S3-kompatibler Bucket verwendet wird. | +| `ImageStorage__AccessKey` | Der Name vom Access-Key. | +| `ImageStorage__AccessKeySecret` | Der Schlüssel vom Access-Key. | +| `ImageStorage__BucketName` | Der Bucket-Name. | + +Der verwendete Access-Key benötigt Rechte zum Erstellen, Lesen und Löschen von Objekten. + +Die Eigenschaften `RegionEndpoint` und `ServiceUrl` schließen sich *gegenseitig aus*! Erstere muss verwendet werden, wenn ein AWS S3-Bucket verwendet wird. Letztere muss verwendet werden, wenn ein S3-kompatibler Bucket von einem Drittanbieter verwendet wird. + +### Azure Blob Storage + +Um Bilder in einem [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs/) Container zu speichern, müssen die folgenden Umgebungsvariablen gesetzt werden: + +| Umgebungsvariable | Beschreibung | +|------------------------------------|-------------------------------------------------------------| +| `ImageStorage__Type` | Muss `Azure` sein. | +| `ImageStorage__StorageAccountName` | Der Name des Azure Blob Storage Account. | +| `ImageStorage__ContainerName` | Der Name des Containers innerhalb vom o.g. Storage Account. | + +Standardmäßig wird ein [DefaultAzureCredential](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) verwendet. Falls also bspw. der turnierplan.NET-Container innerhalb eines Azure App Service betrieben wird, kann für diesen App Service eine Managed Identity erstellt und auf den Blob Storage Account berechtigt werden. Weitere Konfigurationsmöglichkeiten für Deployment-Szenarien, in denen keine Managed Identities verwendet werden können, sind nachfolgend beschrieben. + +Sofern eine Entra ID-basierte Authentifizierung verwendet wird (dies betrifft alle Optionen außer Access Keys), muss die entsprechende Managed Identity bzw. App-Registrierung die Rechte zum Erstellen, Lesen und Löschen von Blobs innerhalb vom Storage Account haben. Dies kann am besten mit der Zuweisung der Rolle [Storage Blob Data Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor) erreicht werden. + +#### Account Key + +Die Erstellung von einem Account Key ist in der [Dokumentation von Microsoft](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal) beschrieben. Um einen Account Key zu verwenden, müssen die folgenden Umgebungsvariablen *zusätzlich* zu den oben genannten gesetzt werden: + +| Umgebungsvariable | Beschreibung | +|-------------------------------|-----------------------------------------------| +| `ImageStorage__UseAccountKey` | Muss `true` sein, um Acount Key zu verwenden. | +| `ImageStorage__AccountKey` | Der eigentliche Account Key. | + +#### Client Secret + +Hierfür ist eine App-Registrierung innerhalb von Entra ID notwendig, welche wie o.g. die notwendigen Zugriffsrechte auf dem Blob Storage Account hat. Innerhalb der App-Registrierung muss zudem ein Client Secret angelegt werden. Um dieses zu verwenden, müssen die folgenden Umgebungsvariablen *zusätzlich* zu den oben genannten gesetzt werden: + +| Umgebungsvariable | Beschreibung | +|---------------------------------|-------------------------------------------------------------| +| `ImageStorage__UseClientSecret` | Muss `true` sein, um Client Secret zu verwenden. | +| `ImageStorage__TenantId` | Die ID des Tenant, wo die App-Registrierung angelegt wurde. | +| `ImageStorage__ClientId` | Die Client-ID der App-Registrierung. | +| `ImageStorage__ClientSecret` | Der Wert des angelegten Client Secrets. | + +## Authentifizierung + +Die folgenden Einstellungen können gesetzt werden, um die Benutzerauthentifizierung von turnierplan.NET zu konfigurieren: + +| Umgebungsvariable | Beschreibung | Standard | +|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| `Identity__AccessTokenLifetime` | Die Gültigkeitsdauer von ausgestellten Access-Tokens. | `00:03:00` | +| `Identity__RefreshTokenLifetime` | Die Gültigkeitsdauer von ausgestellten Refresh-Tokens. Innerhalb diesem Zeitraum ist kein erneuter Login erforderlich. | `1.00:00:00` | +| `Identity__StoragePath` | Das Verzeichnis innerhalb vom Container, wo der Schlüssel zur Signatur ausgesteller Tokens gespeichert wird. | `/var/turnierplan/identity` | +| `Identity__UseInsecureCookies` | Kann auf `true` gesetzt werde, um HTTP Cookies ohne *secure* auszustellen. Dies ist erforderlich, wenn nicht mit HTTPS auf turnierplan.NET zugegriffen wird. | `false` | + +Für ein produktives Deployment sind die Standardwerte ausreichend und müssen nicht geändert werden. + +!!! note + Die Gültigkeitsdauer muss als .NET `TimeSpan` formatiert werden. Das Format ist `HH:mm:ss` bzw. `d.HH:mm:ss` also bspw. `00:03:00` für 3 Minuten oder `1.00:00:00` für 1 Tag. + +## Monitoring + +Der turnierplan.NET-Server kann Telemetriedaten (Logs, Metrics & Traces) an [Azure Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview) senden: + +| Umgebungsvariable | Beschreibung | Standard | +|-----------------------------------------|------------------------------------------------------------------------|----------| +| `ApplicationInsights__ConnectionString` | Kann gesetzt werden, um Daten an Azure Application Insights zu senden. | - | diff --git a/docs/pages/getting-started/images/basic-tournament-config.png b/docs/pages/getting-started/images/basic-tournament-config.png new file mode 100644 index 00000000..bc60f4f0 Binary files /dev/null and b/docs/pages/getting-started/images/basic-tournament-config.png differ diff --git a/docs/pages/getting-started/images/empty-organization.png b/docs/pages/getting-started/images/empty-organization.png new file mode 100644 index 00000000..2fd6fc55 Binary files /dev/null and b/docs/pages/getting-started/images/empty-organization.png differ diff --git a/docs/pages/getting-started/images/first-tournament-groups.png b/docs/pages/getting-started/images/first-tournament-groups.png new file mode 100644 index 00000000..65f96a97 Binary files /dev/null and b/docs/pages/getting-started/images/first-tournament-groups.png differ diff --git a/docs/pages/getting-started/images/first-tournament-match-plan-2.png b/docs/pages/getting-started/images/first-tournament-match-plan-2.png new file mode 100644 index 00000000..5525dc14 Binary files /dev/null and b/docs/pages/getting-started/images/first-tournament-match-plan-2.png differ diff --git a/docs/pages/getting-started/images/first-tournament-match-plan.png b/docs/pages/getting-started/images/first-tournament-match-plan.png new file mode 100644 index 00000000..29d18089 Binary files /dev/null and b/docs/pages/getting-started/images/first-tournament-match-plan.png differ diff --git a/docs/pages/getting-started/images/new-tournament.png b/docs/pages/getting-started/images/new-tournament.png new file mode 100644 index 00000000..e5bce5f7 Binary files /dev/null and b/docs/pages/getting-started/images/new-tournament.png differ diff --git a/docs/pages/getting-started/images/report-first-match.png b/docs/pages/getting-started/images/report-first-match.png new file mode 100644 index 00000000..d8e665cf Binary files /dev/null and b/docs/pages/getting-started/images/report-first-match.png differ diff --git a/docs/pages/getting-started/index.md b/docs/pages/getting-started/index.md new file mode 100644 index 00000000..b44611ec --- /dev/null +++ b/docs/pages/getting-started/index.md @@ -0,0 +1,75 @@ +--- +icon: lucide/rocket +--- + +# Erste Schritte + +Nach einer Neuinstallation von turnierplan.NET gibt es zunächst nur einen Administratorbenutzer. Für produktive Anwendungen ist es dringend empfohlen, einen nicht-Adminnutzer anzulegen, und diesen für den täglichen Login zu verwenden. Dies wird im folgenden Abschnitt beschrieben. Es können jedoch auch mit dem Administratorbenutzer Turniere angelegt werden. Dies ist im Abschnitt weiter unten beschrieben. + +## Benutzer anlegen + +Zunächst muss sich mit den Zugangsdaten des Administratorbenutzers angemeldet werden. Auf der Startseite ist folgend der *Administrator*-Button sichtbar, welcher zum Administrator-Portal führt. Dort kann ein neuer Benutzer angelegt werden. Zwingend angegeben werden müssen der Benutzername und das Passwort des neuen Benutzers. Nachdem ein Benutzer erstellt wurde, muss ihm noch die Berechtigung erteilt werden, Organisationen zu erstellen. Hierfür muss man in der Zeile des Benutzers auf das Bearbeiten-Symbol drücken, den Haken bei *Benutzer darf neue Organisationen anlegen* setzen und speichern. Anschließend kann der Benutzer sich anmelden und eigenständig neue Organisationen erstellen. + +## Organisation erstellen + +Alle Turniere und andere Objekte, welche innerhalb von turnierplan.NET erstellt werden können, sind immer einer Organisation zugehörig. Eine neue Organisation kann jederzeit auf der Startseite erstellt werden und benötigt lediglich einen Namen. + +!!! tip + Durch die Trennung der Daten in mehrere Organisationen kann gesteuert werden, welche Benutzer innerhalb von welchen Organisationen Daten lesen und Änderungen vornehmen können. + +Für den Start genügt zunächst eine einzelne Organisation. + +## Turnier erstellen + +Ein neues Turnier kann innerhalb einer bestehenden Organisation mit der Schaltfläche *Neues Turnier* erstellt werden: + +![Übersichtsseite einer leeren Organisation](images/empty-organization.png) + +In der Eingabemaske, welche sich darauf öffnet, müssen folgende Informationen bereitgestellt werden: + +- **Name**: Kann frei gewählt werden. +- **Ordner**: Kann optional verwendet werden, um mehrere Turniere zu gruppieren. Dies hat diverse Vorteile, welche separat beschrieben werden. +- **Sichtbarkeit**: Wenn ein Turnier auf *öffentlich* gestellt wird, kann jeder das Turnier mit einem speziellen Link sehen. Wenn das Turnier auf *privat* gestellt wird, kann das Turnier nur als angemeldeter Benutzer gesehen werden. + +![Eingabemaske für ein neues Turnier](images/new-tournament.png) + +Alle o.g. Informationen können nachträglich geändert werden. Nach der Bestätigung der Eingaben öffnet sich die Konfigurationsseite des neu erstellen Turniers: + +### Spielplan konfigurieren + +Auf der Konfigurationsseite wird festgelegt, welche Mannschaften am Turnier teilnehmen, wie diese Mannschaften in Gruppen aufgeteilt sind und welchen Spielmodus das Turnier verwendet. + +Für ein einfaches Turnier genügen die folgenden beiden Schritte:: + +- Erstellen Sie eine neue Gruppe mit der Schaltfläche *Neue Gruppe hinzufügen* +- Legen Sie innerhalb der Gruppe drei Mannschaften an, indem Sie einen Namen in das Textfeld eingeben und die Schaltfläche *Hinzufügen* betätigen + +Die Turnierkonfiguration sieht nun folgendermaßen aus (der untere Teil der Seite ist nachfolgend nicht abgebildet): + +![Eine einfache Turnierkonfiguration mit 3 Mannschaften](images/basic-tournament-config.png) + +Die Änderungen werden erst übernommen, wenn die *Übernehmen*-Schaltfläche am Ende der Seite geklickt wird. + +Anschließend erfolgt eine Weiterleitung auf die Startseite des Turniers. Dort ist der erstellte Spielplan nun sichtbar: + +![Der neu erzeugte Spielplan](images/first-tournament-match-plan.png) + +### Turnierdurchführung + +Bei der Turnierdurchführung werden nacheinander die Ergebnisse der Spiele in den Spielplan eingetragen. Beim Klick auf eines der Spiele öffnet sich hierzu folgender Dialog: + +![Das erste Spielergebnis melden](images/report-first-match.png) + +Der Dialog zeigt die Spielpaarung und bietet die Möglichkeit, für die teilnehmenden Mannschaften die jeweilige Anzahl der Tore einzutagen. Zudem kann neben einem Standardergebnis auch zwischen *n.V.*, *n.E.* oder der sog. *Sonderwertung* entscheiden werden. Letztere eignet sich z.B. im Fall, dass eine Mannschaft nicht angetreten ist. + +Ein Ergebnis kann als *LIVE-Ergebnis* oder als *Endergebnis* gespeichert werden. Spiele mit *LIVE-Ergebnis* werden optisch gekennzeichnet und zählen zudem noch nicht in die Gruppenwertung ein. Erst wenn bei einem Spiel das *Endergebnis* gespeichert wird, zählt das Spiel als beendet. + +Im folgenden Beispiel ist Spiel 1 beendet und Spiel 2 ist derzeit am Laufen: + +![Der Spielplan mit zwei Ergebnissen](images/first-tournament-match-plan-2.png) + +Nach jedem beendeten Spiel werden alle Gruppen durchgerechnet. Beim Klick auf den Reiter *Gruppen* wird die Gruppenstatistik sichtbar: + +![Die Gruppenergebnisse nach drei Spielen](images/first-tournament-groups.png) + +Da es in diesem Turnier nur eine Gruppe sowie keine Finalrunde gibt, ist dies auch gleichzeitig die Endplatzierung des Turniers. diff --git a/docs/pages/img/favicon.ico b/docs/pages/images/favicon.ico similarity index 100% rename from docs/pages/img/favicon.ico rename to docs/pages/images/favicon.ico diff --git a/docs/pages/images/logo-64.png b/docs/pages/images/logo-64.png new file mode 100644 index 00000000..ae427211 Binary files /dev/null and b/docs/pages/images/logo-64.png differ diff --git a/docs/pages/img/logo-192.png b/docs/pages/img/logo-192.png deleted file mode 100644 index 478d9cad..00000000 Binary files a/docs/pages/img/logo-192.png and /dev/null differ diff --git a/docs/pages/index.md b/docs/pages/index.md index b063cdca..2a3c8bfe 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -1,13 +1,28 @@ -# turnierplan.NET +--- +icon: lucide/house +--- -**turnierplan.NET** ist a free and open-source web application for football tournaments +# Startseite -
- +turnierplan.NET ist eine **Open-Source Webanwendung zur Organisation von Turnieren** in Fußballvereinen ([GitHub](https://github.com/turnierplan-NET/turnierplan.NET)). + +
+- :lucide-land-plot: Flexible Spielpläne +- :lucide-shield-user: Benutzerverwaltung +- :lucide-globe: Öffentliche Ansicht für Besucher +- :lucide-file-text: Export von PDF-Dokumenten +- :lucide-settings: Zahlreiche Konfigurationsmöglichkeiten +- :lucide-mail: Verwaltung von Turnieranmeldungen
-
+## Made in Germany + +turnierplan.NET wird hauptsächlich von Fußballfreunden aus dem nordöstlichen Baden-Württemberg, Deutschland verwendet und maintained 🇩🇪. + +Aus diesem Grund sind die Benutzeroberfläche sowie die Dokumentation aktuell ausschließlich in deutscher Sprache verfügbar. Zudem sind die verwendeten Begriffe und Funktionen speziell für die hierzulande üblichen Turniere und Veranstaltungen ausgelegt. Verbesserungsvorschläge sind jederzeit gerne gesehen und können im [Repository](https://github.com/turnierplan-NET/turnierplan.NET) hinterlassen werden. + +Falls turnierplan.NET dennoch für deinen Verein / deine Organisation infrage kommt: Der Quelltext und die Container-Images sind unter der [AGPL-3.0](https://github.com/turnierplan-NET/turnierplan.NET/blob/main/LICENSE) lizenziert und dementsprechend frei verwendbar. Mögliche Vorgehensweisen zum Erstellen eines eigenen Setups sind in der [Installationsanleitung](installation/index.md) beschrieben. -## Getting Started +## Technische Dokumentation -To set up an instance of **turnierplan.NET** on your own server, visit the [Installation](installation.md) guide. +Der Großteil der Anwendung ist in C# geschrieben und basiert auf dem [ASP.NET Core](https://dotnet.microsoft.com/en-us/apps/aspnet) Framework. Die primäre Datenbank, welche von turnierplan.NET verwendet wird, ist [PostgreSQL](https://www.postgresql.org/). Bilddateien werden außerhalb der Datenbank als lokale Dateien oder in einem cloud-basierten Blob-Storage gespeichert. Sämtliche administrative Aufgaben wie das Anlegen von Nutzern oder das Planen und Durchführen von Turnieren werden mit dem turnierplan.NET *Portal* erledigt. Dies ist eine [SPA](https://de.wikipedia.org/wiki/Single-Page-Webanwendung) basierend auf dem [Angular](https://angular.dev/) Framework. Öffentlich sichtbare HTML-Seiten werden allerdings direkt von der ASP.NET-Anwendung gerendert und bereitgestellt. diff --git a/docs/pages/installation.md b/docs/pages/installation.md deleted file mode 100644 index c9bf6655..00000000 --- a/docs/pages/installation.md +++ /dev/null @@ -1,195 +0,0 @@ -# Installation - -**turnierplan.NET** comes as a pre-built container image which can be deployed with minimal configuration. The image is available on GitHub: [ghcr.io/turnierplan-net/turnierplan](https://github.com/turnierplan-NET/turnierplan.NET/pkgs/container/turnierplan) - -## Getting Started - -In the simplest case, you can configure the container to use an in-memory data store. Note that this in-memory store is only meant for quick testing and is obviously not suitable for a production environment. - -```shell -docker run -p 80:8080 -e Database__InMemory="true" ghcr.io/turnierplan-net/turnierplan:latest -``` - -You should see the following output. The credentials of the initial admin user are displayed in the container logs. You can now open up http://localhost in your browser and log in using those credentials. - -``` - __ ___ __ - /\ \__ __ /\_ \ /\ \__ - \ \ ,_\ __ __ _ __ ___ /\_\ __ _ __ _____\//\ \ __ ___ ___ __\ \ ,_\ - \ \ \/ /\ \/\ \/\`'__\/' _ `\/\ \ /'__`\/\`'__\/\ '__`\\ \ \ /'__`\ /' _ `\ /' _ `\ /'__`\ \ \/ - \ \ \_\ \ \_\ \ \ \/ /\ \/\ \ \ \/\ __/\ \ \/ \ \ \L\ \\_\ \_/\ \L\.\_/\ \/\ \ __/\ \/\ \/\ __/\ \ \_ - \ \__\\ \____/\ \_\ \ \_\ \_\ \_\ \____\\ \_\ \ \ ,__//\____\ \__/.\_\ \_\ \_\/\_\ \_\ \_\ \____\\ \__\ - \/__/ \/___/ \/_/ \/_/\/_/\/_/\/____/ \/_/ \ \ \/ \/____/\/__/\/_/\/_/\/_/\/_/\/_/\/_/\/____/ \/__/ - \ \_\ - \/_/ v2025.4.0 - -info: Turnierplan.ImageStorage.Local.LocalImageStorage[0] - Using the following directory for local image storage: '/var/turnierplan/images' -info: Turnierplan.App.DatabaseMigrator[0] - An initial user was created: You can log in using "admin" and the password "53fe6bac-1050-4801-bb11-be2dbd479d66". IMMEDIATELY change this password when running in a production environment! -info: Microsoft.Hosting.Lifetime[14] - Now listening on: http://[::]:8080 -info: Microsoft.Hosting.Lifetime[0] - Application started. Press Ctrl+C to shut down. -info: Microsoft.Hosting.Lifetime[0] - Hosting environment: Production -info: Microsoft.Hosting.Lifetime[0] - Content root path: /app -``` - -## Persisting Data - -The application stores the following data in the `/var/turnierplan` directory: - -- `/var/turnierplan/identity/jwt-signing-key.bin` - The SHA512 signature key used to sign and verify JWT tokens. -- `/var/turnierplan/images/**` - If not configured otherwise (see [section below](#storing-images)), this folder will contain all uploaded image files. - -Therefore, there should always be a volume mapping for this path. - -## Environment Variables - -For a basic installation, the following environment variables must be set: - -| Environment Variable | Description | -|-------------------------------|--------------------------------------------------------------| -| `Turnierplan__ApplicationUrl` | The URL used to access the website. | -| `Database__ConnectionString` | The PostgreSQL connection string with read/write permission. | - -The following environment variables can be set if you want to enable specific features or modify default behavior: - -| Environment Variable | Description | Default | -|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| -| `ApplicationInsights__ConnectionString` | Can be set if you wish that your instance sends telemetry data to [Azure Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview). | - | -| `Identity__AccessTokenLifetime` | Defines the lifetime of issued JWT access tokens. | `00:03:00` | -| `Identity__RefreshTokenLifetime` | Defines the lifetime of issued JWT refresh tokens. | `1.00:00:00` | -| `Turnierplan__InstanceName` | The instance name is displayed in the header/footer of the public pages. If not specified, the string `turnierplan.NET` will be shown instead. | - | -| `Turnierplan__LogoUrl` | The URL of the custom logo to be displayed in the header of the public pages. If not specified, the turnierplan.NET logo will be shown instead. | - | -| `Turnierplan__ImprintUrl` | The URL of your external imprint page if you want it to be linked on the public pages. | - | -| `Turnierplan__PrivacyUrl` | The URL of your external privacy page if you want it to be linked on the public pages. | - | -| `Turnierplan__ImageMaxSize` | The maximum allowed file size when uploading an image file. The default value equates to 8 MiB (8 · 1024 · 1024) | `8388608` | -| `Turnierplan__ImageQuality` | Uploaded images are compressed using the `webp` format with the specified quality. A value of `100` will result in lossless compression being uesd. | `80` | - -!!! note - The token lifetimes must be specified as .NET `TimeSpan` strings. For example `00:03:00` means 3 minutes or `1.00:00.00` means 1 day. - -## Docker Compose - -A minimal recommended configuration for a production environment is shown in the following docker compose example: - -```yaml -services: - turnierplan.database: - image: postgres:latest - environment: - - POSTGRES_PASSWORD=P@ssw0rd - - POSTGRES_DB=turnierplan - volumes: - - turnierplan-database-data:/var/lib/postgresql/data - networks: - - turnierplan - restart: unless-stopped - - turnierplan.app: - image: ghcr.io/turnierplan-net/turnierplan:latest - depends_on: - - turnierplan.database - environment: - - Turnierplan__ApplicationUrl=http://localhost - - Database__ConnectionString=Host=turnierplan.database;Database=turnierplan;Username=postgres;Password=P@ssw0rd - volumes: - - turnierplan-app-data:/var/turnierplan - networks: - - turnierplan - restart: unless-stopped - ports: - - '80:8080' - -volumes: - turnierplan-database-data: - turnierplan-app-data: - -networks: - turnierplan: -``` - -!!! tip - It is recommended to not use the latest tag. Rather, pin your docker services to a specific image version. - -Feel free to modify the environment variables or add additional ones as described in the [environment variables](#environment-variables) section above. - -## Storing Images - -By default, all uploaded image files are stored in the `/var/turnierplan/images` directory. Whilst this is a very simple solution, it also means that the turnierplan.NET backend will serve all image files which can potentially lead to high load on the application server. Alternatively, you can configure the application to save image files to an external storage service. This way, clients can load the images directly from the external service. - -!!! warning - The differnt implementations do not necessarily use the same folder structure to organizie the files. Because of this, migrating from one image storage implementation to another can be difficult - so choose wisely! - -The following implementations are currently available: - -- **Local** - The default, which saves images in a local folder as described above -- **AWS S3** (or compatible) -- **Azure Blob Storage** - -### Configuring AWS S3 - -To store uploaded images in an AWS S3 or S3-compatible bucket, add the following environment variables to your deployment: - -| Environment Variable | Description | -|---------------------------------|--------------------------------------------------| -| `ImageStorage__Type` | The image storage type, **must** be `S3`. | -| `ImageStorage__RegionEndpoint` | The AWS region endpoint, such as `eu-central-1`. | -| `ImageStorage__ServiceUrl` | The service URL when using a non-AWS S3 bucket. | -| `ImageStorage__AccessKey` | The access key identifier. | -| `ImageStorage__AccessKeySecret` | The access key secret. | -| `ImageStorage__BucketName` | The name of the bucket. | - -The access key must have permissions to create, read and delete objects. - -The `RegionEndpoint` and `ServiceUrl` variables are *mutually exclusive*. Use the former if you are using an AWS S3 bucket and use the latter if you use a S3-compatible bucket from a third party. - -### Configuring Azure Blob Storage - -To store uploaded images in an [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs/) container, add the following environment variables to your deployment: - -| Environment Variable | Description | -|------------------------------------|----------------------------------------------| -| `ImageStorage__Type` | The image storage type, **must** be `Azure`. | -| `ImageStorage__StorageAccountName` | The name of the storage account. | -| `ImageStorage__ContainerName` | The name of the blob container. | - -By default, a [DefaultAzureCredential](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) will be used. Therefore, if you use Azure Managed Identities, you won't have to do any further configuration. In addition, this implementation supports two additional means of authentication listed below. - -When using Entra ID based authentication, the managed identity / app registration must have permission to create/read/delete blobs in the storage account. This can be achieved by assigning the [Storage Blob Data Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor) role. - -#### Access key authentication - -Refer to the [documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal) on how to view and manage the access keys. - -The following environment variables must be set to enable access key authentication: - -| Environment Variable | Description | -|-------------------------------|--------------------------------------------------| -| `ImageStorage__UseAccountKey` | Set to `true` to use account key authentication. | -| `ImageStorage__AccountKey` | The value of the account key. | - -#### Client secret authentication - -If you have an Entra ID app registration with the necessary permissions on the storage account, you can set the following environment variables to enable client secret authentication: - -| Environment Variable | Description | -|---------------------------------|---------------------------------------------------------| -| `ImageStorage__UseClientSecret` | Set to `true` to use client credentials authentication. | -| `ImageStorage__TenantId` | The tenant id where the app registration resides. | -| `ImageStorage__ClientId` | The client id of the *app registration*. | -| `ImageStorage__ClientSecret` | The value of the client secret. | - -## Troubleshooting - -Below are troubleshooting steps for some issues you might encounter during installation. - -### Connecting over HTTP - -If you are connecting to a remote (non-`localhost`) turnierplan.NET server via HTTP, you should see a *401 Unauthorized* error after logging in with your valid credentials. This is because turnierplan.NET uses secure cookies by default. You can set the `Identity__UseInsecureCookies` environment variable to `true` to change this behavior. - -!!! danger - Using HTTP is obviously not the way to go if you are connecting over the internet. For local setups this might be fine, though it is still discouraged. Most importantly, it is **not officially supported** because some parts of the client application rely on HTTPS-only browser APIs to work properly (such as clipboard or crypto). diff --git a/docs/pages/installation/index.md b/docs/pages/installation/index.md new file mode 100644 index 00000000..3d59d45d --- /dev/null +++ b/docs/pages/installation/index.md @@ -0,0 +1,109 @@ +--- +icon: lucide/server +--- + +# Installation + +Dieser Artikel beschreibt verschiedene Möglichkeiten, **turnierplan.NET** mithilfe des offiziellen Container-Images bereitzustellen. + +## Container-Image + +Innerhalb der GitHub-Organisation wird für jedes [Release](https://github.com/turnierplan-NET/turnierplan.NET/releases) das offizielle Container-Image veröffentlicht: [ghcr.io/turnierplan-net/turnierplan](https://github.com/turnierplan-NET/turnierplan.NET/pkgs/container/turnierplan) + +Um turnierplan.NET lokal zu testen, kann der folgende Befehl verwendet werden: + +```shell +docker run -p 80:8080 -e Database__InMemory="true" ghcr.io/turnierplan-net/turnierplan:latest +``` + +Die Weboberfläche kann über [localhost:80](http://localhost:80) erreicht werden. Der Benutzername und das initiale Passwort für den Administratorbenutzer werden in den Container-Logs angezeigt. Nach einem Neustart des Containers gehen allerdings alle Daten verloren, da nur eine in-memory Datenbank verwendet wird. + +## Deployment + +Für ein produktives Deployment gibt es nachfolgende Möglichkeiten basierend auf dem Container-Image. Weitere Methoden werden in der Zukunft ergänzt. + +### Docker Compose + +Für die Installation auf einem lokalen Rechner oder einer VM kann im einfachsten Fall Docker Compose verwendet werden. Nachfolgend ein Minimalbeispiel für eine `docker-compose.yaml`: + +```yaml +services: + turnierplan.database: + image: postgres:latest + environment: + - POSTGRES_PASSWORD=P@ssw0rd + - POSTGRES_DB=turnierplan + volumes: + - turnierplan-database-data:/var/lib/postgresql + networks: + - turnierplan + restart: unless-stopped + + turnierplan.application: + image: ghcr.io/turnierplan-net/turnierplan:latest + depends_on: + - turnierplan.database + environment: + - Turnierplan__ApplicationUrl=http://localhost + - Database__ConnectionString=Host=turnierplan.database;Database=turnierplan;Username=postgres;Password=P@ssw0rd + volumes: + - turnierplan-application-data:/var/turnierplan + networks: + - turnierplan + restart: unless-stopped + ports: + - '80:8080' + +volumes: + turnierplan-application-data: + turnierplan-database-data: + +networks: + turnierplan: +``` + +Statt dem `latest`-Tag sollte immer eine spezifische Version für die Images der Datenbank und von turnierplan.NET verwendet werden. Dies ermöglicht eine bessere Kontrolle, welche Updates wann eingespielt werden. Die neuste Version ist auf der [Release-Seite](https://github.com/turnierplan-NET/turnierplan.NET/releases) der Repository auffindbar. + +Die URL, welche letztendlich für den Zugriff auf turnierplan.NET verwendet wird, sollte in der Umgebungsvariable `Turnierplan__ApplicationUrl` spezifiziert werden. Falls bspw. eine Domain `example.com` verwendet wird, sollte der Wert der Umgebungsvariable `https://example.com` sein. Falls turnierplan.NET im lokalen Netzwerk gehostet wird, könnte der Wert bspw. `http://192.168.0.187` sein. Es muss natürlich das korrekte Protokoll (HTTP vs. HTTPS) verwendet werden. + +Die Volume-Mounts sind im [nachfolgenden Abschnitt](#volume-mounts) näher beschrieben. Je nach Konfiguration kann das Volume-Mount vom turnierlpan.NET-Container auch überflüssig sein. + +Beim ersten Starten der Anwendung werden alle Datenbankmigrationen durchgeführt und es wird ein initialer Administrator-Benutzer angelegt. Die Zugangsdaten werden in den Container-Logs angezeigt. Mit diesen Zugangsdaten kann sich in der Weboberfläche unter [localhost:80](http://localhost:80) (bzw. je nach Konfiguration mit entsprechender Domain) eingeloggt werden. + +!!! danger + **Wichtige Sicherheitshinweise**: + + - Das Datenbankpasswort `POSTGRES_PASSWORD` in der Compose-Datei sollte durch ein zufällig generiertes Passwort ersetzt werden. Dementsprechend muss dann auch der Connection-String der Anwendung angepasst werden. + - Der turnierplan.NET-Server sollte niemals ohne Reverse Proxy mit SSL-Terminierung im Internet erreichbar sein. Hierfür kann z.B. [nginx](https://nginx.org/) verwendet werden. + +## Volume Mounts + +Die turnierplan.NET-Anwendung speichert diverse Dateien in folgendem Verzeichnis innerhalb vom Container: `/var/turnierplan`. Bei einer Standardkonfiguration sollte dieses Verzeichnis in einem Docker Volume oder vergleichbar persistiert werden. Die folgenden Daten werden innerhalb vom o.g. Verzeichnis gespeichert: + +- **Bild-Uploads**: Sofern keine anderweitige Speicherung von Bildern (wie z.B. S3) konfiguriert ist. +- **JWT Signatur-Schlüssel**: Sofern kein Schlüssel via Umgebungsvariable spezifiziert wird, generiert die Anwendung beim ersten Start einen zufälligen symmetrischen SHA512 Schlüssel zur Signatur der JWT-Tokens. Wenn der Schlüssel nicht persistiert wird, wird er bei jedem Start des Servers neu generiert und alle zuvor ausgestellten JWT-Tokens werden ungültig. + +## Konfiguration + +turnierplan.NET bietet zahlreiche Konfigurationsmöglichkeiten zur Anbindung von Externen System sowie zur Individualisierung. Alle Optionen können mit Umgebungsvariablen gesetzt werden und sind in der [Konfigurationsanleitung](./configuration) aufgelistet und beschrieben. + +## Erste Schritte + +Die Anmeldung als Administrator erfolgt mit den Zugangsdaten, welche beim ersten Programmstart generiert werden, bzw. in der Konfiguration vorgegeben sind. Weitere Schritte sind auf der entsprechenden Seite [Erste Schritte](../getting-started/index.md) der Dokumentation beschrieben. + +## Aktualisierung + +Die verwendete Version von turnierplan.NET kann jederzeit auf eine neuere aktualisiert werden. Etwaige Datenbankmigrationen werden beim ersten Start sequenziell angewandt - auch wenn Versionen übersprungen werden. Allerdings sollten vor jeder Aktualisierung *immer* die [Release-Notes](https://github.com/turnierplan-NET/turnierplan.NET/releases) gelesen werden! Es kann jederzeit nicht-rückwärtskompatible Änderungen geben. + +Zudem wird empfohlen, vor jeder Aktualisierung der turnierplan.NET-Anwendung *oder* der verwendeten PostgreSQL-Version ein Datenbankupdate zu erstellen. Dies kann z.B. mit dem [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)-Tool gemacht werden. + +## Fehlerbehebung + +Nachfolgend beschrieben sind Fehler, welche bei einer Neuinstallation auftreten können. + +### Verbindung per HTTP + +Beim Zugriff auf einen nicht-lokalen turnierplan.NET-Server via HTTP sollte standardmäßig ein Fehler *401 Unauthorized* erscheinen. Dies liegt daran, dass turnierplan.NET für die Authentifizierung nach dem Login Cookies verwendet, welche standardmäßig als *secure* ausgestellt werden. Dies hat zur Folge, dass Browser den Cookie nur bei lokalen Verbindungen oder über HTTPS mitschicken. Um turnierplan.NET dennoch verwenden zu können, muss die `Identity__UseInsecureCookies` auf `true` gesetzt werden. Siehe auch [Konfiguration der Authentifizierung](configuration.md#authentifizierung). + +!!! warning + Die Verwendung von HTTP-Verbindungen über das Internet ist **absolut nicht empfohlen**, da persönliche Daten und Passwörter somit unverschlüsselt übertragen werden würden. Zudem ist nicht ausgeschlossen, dass Teile der Webanwendung nicht korrekt funktionieren, falls diese HTTPS-exklusive Browser-APIs verwenden (bspw. Zwischenablage oder *crypto*). diff --git a/docs/pages/releases/index.md b/docs/pages/releases/index.md new file mode 100644 index 00000000..3a71c120 --- /dev/null +++ b/docs/pages/releases/index.md @@ -0,0 +1,14 @@ +--- +icon: lucide/package +--- + +# Releases + +Die Hauptreleases von turnierplan.NET folgen prinzipiell immer dem Schema `Jahr.Zahl` also bspw. `2025.3` für das dritte Release im Jahr 2025. Mit jedem Release kommen i.d.R. neue Features und zahlreiche Verbesserungen dazu. Die Migration von einer älteren Version auf eine neuere ist immer unterstützt, wobei auch Versionen übersprungen werden können. Ein Downgrade von einer beliebigen Version auf eine ältere Version ist **nicht** möglich. + +Zusätzlich kann es für das aktuellste Hauptrelease kleinere Releases mit Sicherheitsupdates oder Bugfixes geben. In diesem Fall wird hinter dem Hauptrelease die Patch-Version hochgezählt. Also bspw. `2025.3.0`, `2025.3.1`, usw. Mit jedem Hauptrelease endet der Support für das vorherige Hauptrelease. + +Alle bisherigen Releases mit den detaillierten Änderungen sind in der [Release-Seite](https://github.com/turnierplan-NET/turnierplan.NET/releases) der GitHub-Repository verfügbar. + +!!! warning + Bei einer Aktualisierung von einem Hauptrelease auf ein neueres kann es zu Breaking Changes kommen! Solche Änderungen und notwendige Handlungsschritte bei einem Update sind ebenfalls im entsprechenden GitHub-Release dokumentiert und sollten stets beachtet werden. diff --git a/docs/requirements.txt b/docs/requirements.txt index 016bb16d..32b234e8 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1 @@ -mkdocs +zensical==0.0.24 diff --git a/docs/zensical.toml b/docs/zensical.toml new file mode 100644 index 00000000..592caf7f --- /dev/null +++ b/docs/zensical.toml @@ -0,0 +1,63 @@ +[project] + +site_name = "turnierplan.NET Dokumentation" +site_author = "turnierplan.NET" +site_url = "https://docs.turnierplan.net/" +site_description = "Admin- und Benutzerdokumentation für turnierplan.NET" + +repo_name = "turnierplan-NET/turnierplan.NET" +repo_url = "https://github.com/turnierplan-NET/turnierplan.NET" +edit_uri = "blob/main/docs/pages/" + +copyright = "Copyright © 2026 Elias Hörner" + +docs_dir = "pages" +extra_css = ["assets/turnierplan.css"] + +nav = [ + { "Startseite" = "index.md" }, + { "Installation" = "installation/index.md" }, + { "Konfiguration" = "configuration/index.md" }, + { "Erste Schritte" = "getting-started/index.md" }, + { "Releases" = "releases/index.md" } +] + +[project.theme] + +favicon = "images/favicon.ico" +logo = "images/logo-64.png" +language = "de" +font = false + +features = [ + "content.action.edit", + "content.code.annotate", + "content.code.copy", + "content.footnote.tooltips", + "content.tabs.link", + "content.tooltips", + "navigation.expand", + "navigation.footer", + "navigation.indexes", + "navigation.instant", + "navigation.instant.prefetch", + "navigation.path", + "navigation.sections", + "navigation.top", + "navigation.tracking", + "search.highlight", + # "toc.follow", + # "toc.integrate", +] + +[[project.theme.palette]] +scheme = "default" +accent = "green" +toggle.icon = "lucide/sun" +toggle.name = "In dunklen Modus wechseln" + +[[project.theme.palette]] +scheme = "slate" +accent = "green" +toggle.icon = "lucide/moon" +toggle.name = "In hellen Modus wechseln"