Skip to content

Commit d338197

Browse files
eliaspreliaspr
authored
Update documentation toolchain and rewrite existing pages (#361)
1 parent b9159e5 commit d338197

24 files changed

Lines changed: 431 additions & 303 deletions

‎.github/workflows/build.yaml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,22 +89,22 @@ jobs:
8989
id-token: write
9090
steps:
9191
- uses: actions/checkout@v5
92-
- name: "Set up Python 3.12"
92+
- name: "Set up Python 3.x"
9393
uses: actions/setup-python@v5
9494
with:
95-
python-version: "3.12"
95+
python-version: "3.x"
9696
- name: "Install requirements"
9797
run: "python3 -m pip install -r requirements.txt"
9898
working-directory: "docs"
9999
- name: "Build documentation"
100-
run: "python3 -m mkdocs build"
100+
run: "zensical build --clean"
101101
working-directory: "docs"
102102
- name: "Setup Pages"
103103
uses: actions/configure-pages@v5
104-
- name: Upload artifact
104+
- name: "Upload artifact"
105105
uses: actions/upload-pages-artifact@v3
106106
with:
107107
path: "docs/site"
108-
- name: Deploy to GitHub Pages
108+
- name: "Deploy to GitHub Pages"
109109
id: deployment
110110
uses: actions/deploy-pages@v4

‎.github/workflows/documentation.yaml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,13 @@ jobs:
1212
runs-on: ubuntu-24.04
1313
steps:
1414
- uses: actions/checkout@v5
15-
- name: "Set up Python 3.12"
15+
- name: "Set up Python 3.x"
1616
uses: actions/setup-python@v5
1717
with:
18-
python-version: "3.12"
18+
python-version: "3.x"
1919
- name: "Install requirements"
2020
run: "python3 -m pip install -r requirements.txt"
2121
working-directory: "docs"
2222
- name: "Build documentation"
23-
run: "python3 -m mkdocs build"
23+
run: "zensical build --clean"
2424
working-directory: "docs"

‎README.md‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,12 @@
66

77
## Introduction
88

9-
**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).
9+
**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.
1010

11-
> [!NOTE]
12-
> The user interface is currently only available in German 🇩🇪
13-
14-
## Installation
15-
16-
If you want to install **turnierplan.NET** on your server, please visit the [Installation guide](https://docs.turnierplan.net/installation).
11+
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).
1712

18-
## Documentation
19-
20-
Visit the **turnierplan.NET** documentation using the following link: [docs.turnierplan.net](https://docs.turnierplan.net)
21-
22-
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.
13+
> [!NOTE]
14+
> The user interface and documentation are currently only available in German 🇩🇪
2315
2416
## Development
2517

‎docs/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
## turnierplan.NET · Documentation
22

3-
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).
3+
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).
44

5-
In order to build the documentation locally, you must first install Python and [mkdocs](https://www.mkdocs.org):
5+
In order to build the documentation locally, you must first install Python and `zensical`:
66

77
```
88
pip install -r requirements.txt
99
```
1010

11-
Next, you can either view the rendered documentation using the mkdocs-build-in server or you can generate the static website files:
11+
Next, you can either view the rendered documentation using the zensical built-in server or you can generate the static website files:
1212

1313
```
14-
python3 -m mkdocs serve # starts a local web server on port 8000
15-
python3 -m mkdocs build # generates static web site artifacts into the 'site' directory
14+
python3 -m zensical serve # starts a local web server on port 8000
15+
python3 -m zensical build # generates static web site artifacts into the 'site' directory
1616
```

‎docs/mkdocs.yml‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎docs/pages/assets/turnierplan.css‎

Lines changed: 8 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,11 @@
1-
/*
2-
* Some style improvements for the footer
3-
*/
4-
5-
footer hr {
6-
opacity: 0.2;
7-
}
8-
9-
footer p {
10-
font-size: 0.8em;
11-
margin-bottom: 0.3em;
12-
}
13-
14-
/*
15-
* Remove the sidebar on the homepage, copied from the mkdocs.org documentation
16-
* => https://github.com/mkdocs/mkdocs/blob/2862536793b3c67d9d83c33e0dd6d50a791928f8/docs/css/extra.css#L48
17-
*/
18-
19-
body.homepage > div.container > div.row > div.col-md-3 {
20-
display: none;
21-
}
22-
23-
body.homepage > div.container > div.row > div.col-md-9 {
24-
margin-left: 0;
25-
flex: 0 0 100%;
26-
max-width: 100%;
27-
}
28-
/*
29-
* Some additional style changes for the homepage
30-
*/
31-
32-
body.homepage h1 {
33-
margin-top: 2em;
34-
margin-bottom: 0.7em;
35-
text-align: center;
36-
font-weight: bold;
37-
}
38-
39-
body.homepage > div.container p:first-of-type {
40-
text-align: center;
1+
.md-copyright {
2+
/* Decrease size of the footer text */
3+
font-size: 0.8em;
414
}
425

43-
body.homepage > div.container img:first-of-type {
44-
padding: unset;
45-
border: unset;
6+
.md-content img {
7+
/* Center images and add small shadow */
8+
display: block;
9+
margin: 0 auto;
10+
box-shadow: 0 0 3px rgba(0, 0, 0, 0.2);
4611
}

‎docs/pages/configuration/index.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
icon: lucide/wrench
3+
---
4+
5+
# Konfiguration
6+
7+
Unabhängig vom Deployment und der verwendeten Hardware/Server bietet turnierplan.NET zahlreiche Konfigurationsmöglichkeiten, welche nachfolgend näher beschrieben sind.
8+
9+
## Erforderliche Einstellungen
10+
11+
Für eine produktive Installation müssen die folgenden Umgebungsvariablen zwingend gesetzt sein:
12+
13+
| Umgebungsvariable | Beschreibung |
14+
|-------------------------------|--------------------------------------------------------------------|
15+
| `Turnierplan__ApplicationUrl` | Die URL, welche für den Web-Zugriff auf den Server verwendet wird. |
16+
| `Database__ConnectionString` | Connection-String für die PostgreSQL-Datenbank. |
17+
18+
## Allgemeine Einstellungen
19+
20+
Die folgenden Einstellungen können gesetzt werden, um das allgemeine Aussehen und Verhalten von turnierplan.NET zu konfigurieren:
21+
22+
| Umgebungsvariable | Beschreibung | Standard |
23+
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
24+
| `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. | - |
25+
| `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. | - |
26+
| `Turnierplan__ImprintUrl` | Die URL für den Verweis auf ein externes Impressum, welches bspw. auf Ihrer Vereins-/Firmenseite gehostet ist. | - |
27+
| `Turnierplan__PrivacyUrl` | Die URL für den Verweis auf eine externe Datenschutz-Seite, welche bspw. auf Ihrer Vereins-/Firmenseite gehostet ist. | - |
28+
| `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. | - |
29+
| `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. | - |
30+
31+
## Bilder-Uploads
32+
33+
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:
34+
35+
| Umgebungsvariable | Beschreibung | Standard |
36+
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------|
37+
| `Turnierplan__ImageMaxSize` | Die maximale Dateigröße für Bild-Uploads in Bytes. Der Standard-Wert entspricht 8 MiB (8 · 1024 · 1024) | `8388608` |
38+
| `Turnierplan__ImageQuality` | Die Qualitätseinstellung für Bild-Uploads. Ein Wert von `100` entspricht einer verlustfreien Komprimierung. | `80` |
39+
| `ImageStorage__StoragePath` | Das Verzeichnis innerhalb vom Container, hochgeladene Bilder gespeichert werden. | `/var/turnierplan/images` |
40+
41+
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:
42+
43+
- **AWS S3** (oder kompatibler Dienst)
44+
- **Azure Blob Storage**
45+
46+
!!! warning
47+
Die nachfolgend vorgestellten Alternativen verwenden nicht zwangsläufig eine identische Verzeichnisstruktur zur Organisation der Dateien. Dadurch wird eine nachträgliche Umstellung ggf. erschwert!
48+
49+
### AWS S3
50+
51+
Um Bilder in einem AWS S3 oder S3-kompatiblen Bucket zu speichern, müssen die folgenden Umgebungsvariablen gesetzt werden:
52+
53+
| Umgebungsvariable | Beschreibung |
54+
|---------------------------------|------------------------------------------------------------------|
55+
| `ImageStorage__Type` | Muss `S3` sein. |
56+
| `ImageStorage__RegionEndpoint` | Der Name der AWS-Region, bspw. `eu-central-1`. |
57+
| `ImageStorage__ServiceUrl` | Die Service-URL, falls ein S3-kompatibler Bucket verwendet wird. |
58+
| `ImageStorage__AccessKey` | Der Name vom Access-Key. |
59+
| `ImageStorage__AccessKeySecret` | Der Schlüssel vom Access-Key. |
60+
| `ImageStorage__BucketName` | Der Bucket-Name. |
61+
62+
Der verwendete Access-Key benötigt Rechte zum Erstellen, Lesen und Löschen von Objekten.
63+
64+
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.
65+
66+
### Azure Blob Storage
67+
68+
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:
69+
70+
| Umgebungsvariable | Beschreibung |
71+
|------------------------------------|-------------------------------------------------------------|
72+
| `ImageStorage__Type` | Muss `Azure` sein. |
73+
| `ImageStorage__StorageAccountName` | Der Name des Azure Blob Storage Account. |
74+
| `ImageStorage__ContainerName` | Der Name des Containers innerhalb vom o.g. Storage Account. |
75+
76+
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.
77+
78+
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.
79+
80+
#### Account Key
81+
82+
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:
83+
84+
| Umgebungsvariable | Beschreibung |
85+
|-------------------------------|-----------------------------------------------|
86+
| `ImageStorage__UseAccountKey` | Muss `true` sein, um Acount Key zu verwenden. |
87+
| `ImageStorage__AccountKey` | Der eigentliche Account Key. |
88+
89+
#### Client Secret
90+
91+
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:
92+
93+
| Umgebungsvariable | Beschreibung |
94+
|---------------------------------|-------------------------------------------------------------|
95+
| `ImageStorage__UseClientSecret` | Muss `true` sein, um Client Secret zu verwenden. |
96+
| `ImageStorage__TenantId` | Die ID des Tenant, wo die App-Registrierung angelegt wurde. |
97+
| `ImageStorage__ClientId` | Die Client-ID der App-Registrierung. |
98+
| `ImageStorage__ClientSecret` | Der Wert des angelegten Client Secrets. |
99+
100+
## Authentifizierung
101+
102+
Die folgenden Einstellungen können gesetzt werden, um die Benutzerauthentifizierung von turnierplan.NET zu konfigurieren:
103+
104+
| Umgebungsvariable | Beschreibung | Standard |
105+
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
106+
| `Identity__AccessTokenLifetime` | Die Gültigkeitsdauer von ausgestellten Access-Tokens. | `00:03:00` |
107+
| `Identity__RefreshTokenLifetime` | Die Gültigkeitsdauer von ausgestellten Refresh-Tokens. Innerhalb diesem Zeitraum ist kein erneuter Login erforderlich. | `1.00:00:00` |
108+
| `Identity__StoragePath` | Das Verzeichnis innerhalb vom Container, wo der Schlüssel zur Signatur ausgesteller Tokens gespeichert wird. | `/var/turnierplan/identity` |
109+
| `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` |
110+
111+
Für ein produktives Deployment sind die Standardwerte ausreichend und müssen nicht geändert werden.
112+
113+
!!! note
114+
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.
115+
116+
## Monitoring
117+
118+
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:
119+
120+
| Umgebungsvariable | Beschreibung | Standard |
121+
|-----------------------------------------|------------------------------------------------------------------------|----------|
122+
| `ApplicationInsights__ConnectionString` | Kann gesetzt werden, um Daten an Azure Application Insights zu senden. | - |

‎docs/pages/getting-started/images/basic-tournament-config.png‎

60.6 KB
Loading

‎docs/pages/getting-started/images/empty-organization.png‎

37.9 KB
Loading

‎docs/pages/getting-started/images/first-tournament-groups.png‎

46.4 KB
Loading

0 commit comments

Comments
 (0)