From 39c0bfe6319df1913f26e18423857719d96e31fb Mon Sep 17 00:00:00 2001 From: Nicolai Ort Date: Thu, 16 Jan 2025 21:07:45 +0100 Subject: [PATCH] docs(admin): Full admin docs --- content/admin/_index.de.md | 36 ++++++++++++++++++++++++ content/admin/_index.en.md | 36 ++++++++++++++++++++++++ content/admin/quickstart.de.md | 39 ++++++++++++++++++++++++++ content/admin/quickstart.en.md | 39 ++++++++++++++++++++++++++ content/admin/usergroups.de.md | 50 ++++++++++++++++++++++++++++++++++ content/admin/usergroups.en.md | 50 ++++++++++++++++++++++++++++++++++ content/admin/users.de.md | 49 +++++++++++++++++++++++++++++++++ content/admin/users.en.md | 49 +++++++++++++++++++++++++++++++++ 8 files changed, 348 insertions(+) create mode 100644 content/admin/_index.de.md create mode 100644 content/admin/_index.en.md create mode 100644 content/admin/quickstart.de.md create mode 100644 content/admin/quickstart.en.md create mode 100644 content/admin/usergroups.de.md create mode 100644 content/admin/usergroups.en.md create mode 100644 content/admin/users.de.md create mode 100644 content/admin/users.en.md diff --git a/content/admin/_index.de.md b/content/admin/_index.de.md new file mode 100644 index 0000000..5bfe058 --- /dev/null +++ b/content/admin/_index.de.md @@ -0,0 +1,36 @@ +--- +linkTitle: "Admins" +title: Admin-Doku +weight: 1 +prev: / +next: /admin/quickstart +cascade: + type: docs +--- + +Dieser Teil der Dokumentation befasst sich mit der Installation, Konfiguration und Bedienung des Läufersystems für normale Admins. +Solltest du an der Bedienung für normale Nutzer interessiert sein schau doch mal in den [Nutzerbereich](/user). + +## Services + +Eine kurze Übersicht über die verschiedenen Services des Systems und ihre Interaktion + +* Backend: Beinhaltet die Hauptlogik und verwaltet die Daten (via Datenbankanbindung) +* Mailer: Versendet auf Basis von HTML-Templates automatisiert Mails +* Document-Server: Erstellt PDFs (Urkunden, Läuferkarten, Sponsoringerklärungen) aus HTML-Templates +* Frontend: Verwaltungsoberfläche für die Admins und Benutzer:innen des Läufersystems +* Selfservice: Portal in dem sich Bürger- und Firmenläufer:innen registrieren und ihre Daten einsehen können +* Beamershow: Zeigt aktuelle Statistiken und Toplisten zum Event an +* Scanclient: Software für die Scannerstationen +* Docs: Diese Dokumentation + +![Service Diagramms](/images/service_interaction.png) + +## FAQ + +Ein paar der meist gestellten Fragen vorab + +### Warum sehe ich eine Seite nicht? + +Nutzer sehen nur die Seiten im System, für die sie Berechtigungen haben. +Solltest du eine Seite nicht sehen bist du vermutlich nicht voll als Admin berechtigt. diff --git a/content/admin/_index.en.md b/content/admin/_index.en.md new file mode 100644 index 0000000..5f0f221 --- /dev/null +++ b/content/admin/_index.en.md @@ -0,0 +1,36 @@ +--- +linkTitle: "Admins" +title: Admin Documentation +weight: 1 +prev: / +next: /admin/quickstart +cascade: + type: docs +--- + +This part of the documentation deals with the installation, configuration, and operation of the runner system for regular admins. +If you are interested in the operation for regular users, take a look at the [User Area](/user). + +## Services + +A brief overview of the various services of the system and their interaction + +* Backend: Contains the main logic and manages the data (via database connection) +* Mailer: Automatically sends emails based on HTML templates +* Document Server: Creates PDFs (certificates, runner cards, sponsorship declarations) from HTML templates +* Frontend: Administration interface for the admins and users of the runner system +* Self-service: Portal where citizen and company runners can register and view their data +* Beamer Show: Displays current statistics and top lists for the event +* Scan Client: Software for the scanner stations +* Docs: This documentation + +![Service Diagrams](/images/service_interaction.png) + +## FAQ + +A few of the most frequently asked questions in advance + +### Why can't I see a page? + +Users only see the pages in the system for which they have permissions. +If you can't see a page, you are probably not fully authorized as an admin. diff --git a/content/admin/quickstart.de.md b/content/admin/quickstart.de.md new file mode 100644 index 0000000..b77414b --- /dev/null +++ b/content/admin/quickstart.de.md @@ -0,0 +1,39 @@ +--- +title: Schnellstart für Admins +weight: 2 +prev: /admin +next: /admin/users +--- + +Du willst das System schnell aufsetzen und testen? Dann bist du hier genau richtig! + +## Voraussetzungen + +Alle der folgenden Anleitungen gehen davon aus, dass du bereits Docker und Docker-Compose installiert hast. +Die Installationsanleitungen dafür findest du hier: + +* [Docker](https://docs.docker.com/get-docker/) +* [Docker-Compose](https://docs.docker.com/compose/install/) + +## Das ganze System + +> Du willst das ganze System (backend, fronten, document-server) schnell aufsetzen. + +{{% steps %}} + +### Klonen + +Klone das lfk/deployment git repo von: (oder lade es herunter). + +### Starten + +Navigiere nach `docker-compose/full_stack`: `cd deployment/docker-compose/full_stack`. +tarte das System mit `docker-compose up` + +### Nutzen + +Nachdem alles gestartet ist ist kannst du das Frontend aufrufen: (backend: , document-server: ) + +Bei Bedarf können die Ports und andere Einstellungen im docker-compose.yml angepasst werden. + +{{% /steps %}} diff --git a/content/admin/quickstart.en.md b/content/admin/quickstart.en.md new file mode 100644 index 0000000..a1cd984 --- /dev/null +++ b/content/admin/quickstart.en.md @@ -0,0 +1,39 @@ +--- +title: Quick Start for Admins +weight: 2 +prev: /admin +next: /admin/users +--- + +Do you want to set up and test the system quickly? Then you are in the right place! + +## Prerequisites + +All of the following instructions assume that you have already installed Docker and Docker-Compose. +You can find the installation instructions here: + +* [Docker](https://docs.docker.com/get-docker/) +* [Docker-Compose](https://docs.docker.com/compose/install/) + +## The whole system + +> You want to quickly set up the entire system (backend, frontend, document-server). + +{{% steps %}} + +### Clone + +Clone the lfk/deployment git repo from: (or download it). + +### Start + +Navigate to `docker-compose/full_stack`: `cd deployment/docker-compose/full_stack`. +Start the system with `docker-compose up`. + +### Use + +After everything has started, you can access the frontend at: (backend: , document-server: ). + +If necessary, ports and other settings can be adjusted in the docker-compose.yml file. + +{{% /steps %}} diff --git a/content/admin/usergroups.de.md b/content/admin/usergroups.de.md new file mode 100644 index 0000000..d5143b3 --- /dev/null +++ b/content/admin/usergroups.de.md @@ -0,0 +1,50 @@ +--- +title: Benutzergruppen verwalten +weight: 4 +prev: /admin/quickstart +next: /admin/usergroups +--- + +Als Admin kannst du Benutzergruppen anlegen und Benutzer:innen in diese Einsortieren. +Die Benutzer:innen erben dadurch die Berechtigungen aller Gruppen, in denen sie sind. + +So kannst du z.B. alle Admins in die `ADMINS` Gruppe packen, anstatt jeder Benutzer:in langwierig alle Berechtigungen von Hand zuzuweisen. + +## Anlegen + +Um eine neue Benutzergruppe anzulegen öffne im Läufersystem die Seite `Benutzergruppen`. +Über den Button `Neue Gruppe erstellen` kannst du eine neue Benutzergruppe erstellen. +Dabei kannst du der Gruppe einen Namen und (optional) eine Beschreibung geben. + +## Bearbeiten + +Um eine Benutzergruppe zu bearbeiten kannst du in der Benutzergruppenübersicht den Button `Details` für die gewünschte Gruppe anklicken. +In der Übersicht für diese Benutzergruppe kannst du nun den Namen und die Beschreibung anpassen und Berechtigungen einsehen oder bearbeiten. +Wenn du fertig bist klick einfach auf `Änderungen speichern`. + +### Berechtigungen + +{{< callout type="info" >}} + Für die Berechtigung einer Benutzergruppe gibt es eine extra Seite. +{{< /callout >}} + +Um die Berechtigungen einer Gruppe zu bearbeiten kannst du auf der Detailseite der Gruppe auf `Berechtigungen bearbeiten` klicken. +Auf der Berechtigungsseite gibt es zwei Spalten: `Verfügbare`(Berechtigungen, die die Gruppe nicht hat) und `Gewährt`(Berechtigungen, die die Gruppe hat). +Du kannst hier über die Buttons `+` und `-` die Berechtigungen erteilen oder wegnehmen. +Wenn du fertig bist klick einfach auf `Änderungen speichern`. + +## Löschen + +Du kannst eine Benutzergruppe entweder aus der Benutzergruppenübersicht oder der Benutzergruppendetailansicht löschen. +Dabei wird nur die Benutzergruppe samt Berechtigungen gelöscht, nicht ihre Benutzer:innen. + +### In der Benutzergruppenübersicht + +Klick bei der gewünschten Benutzergruppe auf den Button `Löschen`. +Daraufhin wirst du gefragt, ob du die Benutzergruppe wirklich löschen oder abbrechen willst. + +### In der Benutzergruppendetailansicht + +Klick bei der gewünschten Benutzergruppe auf den Button `Details`. +Oben auf der Seite gibt es jetzt den Knopf `Gruppe löschen`. +Daraufhin wirst du gefragt, ob du die Benutzergruppe wirklich löschen oder abbrechen willst. diff --git a/content/admin/usergroups.en.md b/content/admin/usergroups.en.md new file mode 100644 index 0000000..54d44b4 --- /dev/null +++ b/content/admin/usergroups.en.md @@ -0,0 +1,50 @@ +--- +title: Manage User Groups +weight: 4 +prev: /admin/quickstart +next: /admin/usergroups +--- + +As an admin, you can create user groups and assign users to them. +Users inherit the permissions of all the groups they belong to. + +For example, you can put all admins in the `ADMINS` group instead of manually assigning permissions to each user. + +## Create + +To create a new user group, open the `User Groups` page in the runner system. +Click the `Create New Group` button to create a new user group. +You can give the group a name and (optionally) a description. + +## Edit + +To edit a user group, click the `Details` button for the desired group in the user groups overview. +In the overview for this user group, you can now adjust the name and description and view or edit permissions. +When you're done, just click `Save Changes`. + +### Permissions + +{{< callout type="info" >}} + There is a separate page for a user group's permissions. +{{< /callout >}} + +To edit a group's permissions, click `Edit Permissions` on the group's detail page. +On the permissions page, there are two columns: `Available` (permissions the group does not have) and `Granted` (permissions the group has). +You can grant or remove permissions using the `+` and `-` buttons. +When you're done, just click `Save Changes`. + +## Delete + +You can delete a user group either from the user groups overview or the user group detail view. +Only the user group and its permissions will be deleted, not its users. + +### In the User Groups Overview + +Click the `Delete` button for the desired user group. +You will then be asked if you really want to delete the user group or cancel. + +### In the User Group Detail View + +Click the `Details` button for the desired user group. +At the top of the page, there is now a `Delete Group` button. +You will then be asked if you really want to delete the user group or cancel. diff --git a/content/admin/users.de.md b/content/admin/users.de.md new file mode 100644 index 0000000..e57a1a2 --- /dev/null +++ b/content/admin/users.de.md @@ -0,0 +1,49 @@ +--- +title: Benutzer:innen verwalten +weight: 3 +prev: /admin/quickstart +next: /admin/usergroups +--- + +Als Admin kannst du Benutzer:innen anlegen. +Benutzer:innen können sich in der Läuferverwaltung und am Backend (API) anmelden und im Rahmen ihrer Berechtigungen damit Arbeiten. +Benutzer:innen kannst du Berechtigungen direkt zuweisen oder sie beliebig vielen Gruppen zuweisen, von denen sie dann Berechtigungen erben. + +## Anlegen + +Um eine neue Benutzer:in anzulegen öffne im Läufersystem die Seite `Benutzer`. +Über den Button `Benutzer anlegen` kannst du eine neue Benutzer:in erstellen. +Dabei kannst du dem Kontakt eine(n) Namen, Benutzernamen, Passwort und E-Mail Adresse geben. + +## Bearbeiten + +Um eine Benutzer:in zu bearbeiten kannst du in der Benutzerübersicht den Button `Details` für die gewünschte Benutzer:in anklicken. +In der Übersicht für diesen Kontakt kannst du nun den Namen, Benutzernamen, die E-Mail, Gruppen und Berechtigungen anpassen. +Wenn du fertig bist klick einfach auf `Änderungen speichern`. + +### Berechtigungen + +{{< callout type="info" >}} +Für die Berechtigung einer Benutzer:in gibt es eine extra Seite. +{{< /callout >}} + +Um die Berechtigungen einer Benutzer:in zu bearbeiten kannst du auf der Detailseite der Benutzer:in auf `Berechtigungen bearbeiten` klicken. +Auf der Berechtigungsseite gibt es drei Spalten: `Verfügbare`(Berechtigungen, die die Benutzer:in nicht direkt hat), `Direkt erteilte`(Berechtigungen, die die Benutzer:in direkt hat) und `geerbte`(Berechtigungen, die die Benutzer:in von ihren Benutzergruppen geerbt hat). +Du kannst hier über die Buttons `+` und `-` die direkten Berechtigungen erteilen oder wegnehmen. +Wenn du fertig bist klick einfach auf `Änderungen speichern`. + +## Löschen + +Du kannst eine Benutzer:in entweder aus der Benutzerübersicht oder der Benutzerdetailansicht löschen. +Dabei wird nur die Benutzer:in samt Berechtigungen gelöscht. + +### In der Benutzerübersicht + +Klick bei der gewünschten Benutzer:in auf den Button `Löschen`. +Daraufhin wirst du gefragt, ob du die Benutzer:in wirklich löschen oder abbrechen willst. + +### In der Benutzerdetailansicht + +Klick bei der gewünschten Benutzer:in auf den Button `Details`. +Oben auf der Seite gibt es jetzt den Knopf `Benutzer:in löschen`. +Daraufhin wirst du gefragt, ob du die Benutzer:in wirklich löschen oder abbrechen willst. \ No newline at end of file diff --git a/content/admin/users.en.md b/content/admin/users.en.md new file mode 100644 index 0000000..58b4f3a --- /dev/null +++ b/content/admin/users.en.md @@ -0,0 +1,49 @@ +--- +title: Manage Users +weight: 3 +prev: /admin/quickstart +next: /admin/usergroups +--- + +As an admin, you can create users. +Users can log in to the runner management system and the backend (API) and work within their permissions. +You can assign permissions directly to users or assign them to any number of groups from which they inherit permissions. + +## Create + +To create a new user, open the `Users` page in the runner system. +Click the `Create User` button to create a new user. +You can give the contact a name, username, password, and email address. + +## Edit + +To edit a user, click the `Details` button for the desired user in the user overview. +In the overview for this contact, you can now adjust the name, username, email, groups, and permissions. +When you are done, simply click `Save Changes`. + +### Permissions + +{{< callout type="info" >}} +There is a separate page for a user's permissions. +{{< /callout >}} + +To edit a user's permissions, click `Edit Permissions` on the user's detail page. +On the permissions page, there are three columns: `Available` (permissions the user does not have directly), `Directly Granted` (permissions the user has directly), and `Inherited` (permissions the user has inherited from their user groups). +You can grant or remove direct permissions using the `+` and `-` buttons. +When you are done, simply click `Save Changes`. + +## Delete + +You can delete a user either from the user overview or the user detail view. +Only the user and their permissions will be deleted. + +### In the User Overview + +Click the `Delete` button for the desired user. +You will then be asked if you really want to delete the user or cancel. + +### In the User Detail View + +Click the `Details` button for the desired user. +At the top of the page, there is now a `Delete User` button. +You will then be asked if you really want to delete the user or cancel. \ No newline at end of file