diff --git a/doc/_config.yml b/doc/_config.yml index 0730af45..26fd44cc 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -27,6 +27,7 @@ baseurl: '' # the subpath of your site, e.g. /blog url: '' # the base hostname & protocol for your site, e.g. http://example.com twitter_username: github_username: zoomyboy +source: page # Aux links for the upper right navigation aux_links: @@ -41,9 +42,19 @@ color_scheme: dark plugins: - jekyll-feed callouts: - para: - title: Info + block: color: grey-lt + warning: + color: yellow + title: Warnung + info: + color: blue + title: Info +defaults: + - scope: + path: 'assets/img' + values: + image: true # Exclude from processing. # The following items will not be processed, by default. # Any item listed under the `exclude:` key here will be automatically added to diff --git a/doc/about.md b/doc/about.md deleted file mode 100644 index e6e2bcd6..00000000 --- a/doc/about.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: page -title: About ---- - -This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/) - -You can find the source code for Minima at GitHub: -[jekyll][jekyll-organization] / -[minima](https://github.com/jekyll/minima) - -You can find the source code for Jekyll at GitHub: -[jekyll][jekyll-organization] / -[jekyll](https://github.com/jekyll/jekyll) - - -[jekyll-organization]: https://github.com/jekyll diff --git a/build.sh b/doc/build.sh old mode 100644 new mode 100755 similarity index 100% rename from build.sh rename to doc/build.sh diff --git a/doc/firststeps/index.md b/doc/firststeps/index.md deleted file mode 100644 index c6b49eba..00000000 --- a/doc/firststeps/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: page -title: Erste Schritte -has_children: true ---- - -# Erste Schritte - -Dieses Dokument beschreibt die ersten Grundeinstellungen nach der Installation von Adrema. - -Als erstes solltest du deine Zugangsdaten und deine Gruppierungsnummer, sowie die "Über-Gruppierung" herausfinden. - -Melde dich dann mit deinen Benutzerdaten an. - -## 1. NaMi-Zugangsdaten eingeben - -Gebe deine NaMi-Zugangsdaten ein. Diese werden danach geprüft. Wenn diese korrekt sind, wirst du zum nächsten Schritt weitergeleitet. - -## 2. Suchparameter definieren - -Nun solltest du Parameter für die NaMi-Suche definieren, die beim täglichen Abruf angewendet werden. - -Gebe deine Gruppierungsnummer und deren Ober-Gruppierungen ein. Du bekommst dann eine Vorschau eingeblendet. - -> Dies ist nur eine Vorschau der Suchergebnisse. Es findet hier noch kein realer Abgleich statt. - -## 3. Standard-Gruppierungsnummer - -Für einige Prozesse benötigt Adrema die Standard-Gruppierungsnummer. Dies ist i.d.R. die Gruppierungsnummer deiner lokalen Gruppierung die du verwalten willst (z.B. dein Stamm). - -## 4. Initialisierung starten - -Danach führt Adrema im Hintergrund selbstständig einen ersten Abgleich durch. Dies kann je nach Datenmenge einige Minuten bis Stunden dauern. diff --git a/doc/firststeps/install.md b/doc/firststeps/install.md deleted file mode 100644 index b45dfd01..00000000 --- a/doc/firststeps/install.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: page -title: Installation -parent: Erste Schritte ---- - -# Versionierung - -## Ein Beispiel - -> Eine Stammesvorsitzende - nennen wir sie Petra - öffnet ein Mitglied in NaMi, um eine Änderung der Adresse vorzunehmen -> -> Währenddessen ändert jemand anderes - nennen wir ihn Bob - die Telefonnummer des gleichen Mitglieds -> -> Petra speichert nun das Mitglied mit der __neuen Adresse__ ab, obwohl bei ihr im "bearbeiten-Formular" noch die __alte Telefonnummer__ steht. -> -> Resultat: Die Änderung der Adresse (Petras Änderung) wurde übernommen. Die Änderung von Bob (die Änderung der Telefonnummer) wurde aber überschrieben. -> Das Mitglied hat also nun die neue Adresse, aber noch die alte Telefonnummer. - -Da auch übergeordnete Ebenen auf die Mitglieder der DPSG Zugriff haben und diese häufig auch bearbeiten können, ist dieses Szenario durchaus denkbar. - -Die NaMi löst dieses Problem intern mit einer Versionsnummer, die jedes Mal um 1 erhöht wird, wenn jemand Änderungen an den Basisdaten vornimmt. So lässt sich feststellen, dass zwischenzeitlich eine Änderung durch eine\*n dritte\*n erfolgt ist. - -## Versionen in Adrema - -Die Adrema macht sich dieses System zunutze. Vor einem Update wird geprüft, ob zwischenzeitlich ein Update in NaMi vorgenommen wurde. Ist das der Fall, wird ein Hinweis angezeigt: - -Du hast hier nun zwei Optionen: - -> 1. Du aktualisierst das Mitglied in Adrema. Dadurch werden deine Änderungen rückgängig gemacht und das Mitglied erneut aus NaMi abgerufen. Danach kannst du deine Änderung erneut vornehmen. -> -> 2. Du aktualisierst das Mitglied. Dabei spielt der aktuelle NaMi-Stand keine Rolle. __Dabei kann es allerdings zu Datenverlust kommen__ (wie oben beschrieben). - -Auf diese Art und Weise ist sichergestellt, dass Änderungen sich nicht gegenseitig überschreiben. diff --git a/doc/page/_includes/imgcap.html b/doc/page/_includes/imgcap.html new file mode 100644 index 00000000..19eb696f --- /dev/null +++ b/doc/page/_includes/imgcap.html @@ -0,0 +1,4 @@ +
+ +
{{ include.caption }}
+
diff --git a/doc/page/assets/img/init-confirm.jpg b/doc/page/assets/img/init-confirm.jpg new file mode 100644 index 00000000..543be84a Binary files /dev/null and b/doc/page/assets/img/init-confirm.jpg differ diff --git a/doc/page/assets/img/init-default-groupid.jpg b/doc/page/assets/img/init-default-groupid.jpg new file mode 100644 index 00000000..fb73fb21 Binary files /dev/null and b/doc/page/assets/img/init-default-groupid.jpg differ diff --git a/doc/page/assets/img/init-login.jpg b/doc/page/assets/img/init-login.jpg new file mode 100644 index 00000000..b87b7345 Binary files /dev/null and b/doc/page/assets/img/init-login.jpg differ diff --git a/doc/page/assets/img/init-members.jpg b/doc/page/assets/img/init-members.jpg new file mode 100644 index 00000000..34953df0 Binary files /dev/null and b/doc/page/assets/img/init-members.jpg differ diff --git a/doc/page/assets/img/member.jpg b/doc/page/assets/img/member.jpg new file mode 100644 index 00000000..f54f95d8 Binary files /dev/null and b/doc/page/assets/img/member.jpg differ diff --git a/doc/page/assets/img/nami-login-init.jpg b/doc/page/assets/img/nami-login-init.jpg new file mode 100644 index 00000000..b87b7345 Binary files /dev/null and b/doc/page/assets/img/nami-login-init.jpg differ diff --git a/doc/page/firststeps/first.md b/doc/page/firststeps/first.md new file mode 100644 index 00000000..47d11fbc --- /dev/null +++ b/doc/page/firststeps/first.md @@ -0,0 +1,47 @@ +--- +layout: page +title: Grundeinstellungen +parent: Erste Schritte +nav_order: 2 +--- + +Dieses Dokument beschreibt die ersten Grundeinstellungen nach der Installation von Adrema. + +## Anmeldung in NaMi + +Als erstes solltest du deine Zugangsdaten zu NaMi (deine Mitgliedsnummer und dein Passwort) eingeben, um dich einmalig anzumelden. Deine Zugangsdaten werden in Adrema gespeichert und müssen nur bei der Ersteinrichtung einmalig angegeben werden. + +{: .info } +Der NaMi Benutzer sollte Schreibrechte auf der gewünschten Gruppierung haben. Grundsätzlich lässt sich Adrema auch mit NaMi-Accounts nutzen, die nur Leserechte haben. Dann kann man aber keine NaMi-Daten aktualisieren, bzw nur Adrema-interne Änderungen vornehmen (was langweilig ist :D ) + +{% include imgcap.html img='init-login' caption="Login in NaMi" %} + +## Suchparameter definieren + +Nun solltest du Parameter für die NaMi-Suche definieren, die beim täglichen Abruf angewendet werden. + +Dabei ist es notwendig, zuerst die Diözesan-Gruppierungsnummer anzugeben. Wenn du diese nicht weißt, gehe in NaMi auf den Reiter "Suche" und wähle bei "1. Ebene (Diözese)" deine Gruppierung aus. Dort erscheint dann die Gruppierungsnummer (eine 6-Stellige Zahl). Diese ist hier einzugeben. + +Danach kannst du mit der Bezirks-Ebene weiter verfahren (analog "2. Ebene (Bezirk)" in NaMi). + +Du kannst beim Mitglieds-Status auswählen, ob du nur aktive Mitglieder, nur inaktive Mitglieder oder beides ("kein") abrufen willst. + +Du bekommst im unteren Bereich eine Vorschau eingeblendet, welche Mitglieder abgerufen werden würden. Dies ist lediglich eine Vorschau eines Live-Abrufs aus NaMi - es handelt sich also nicht um einen vollständigen Adrema-Datensatz, da wichtige Infos wie z.B. Geburtsdaten in diesem Prozess noch nicht abgerufen werden. + +{% include imgcap.html img='init-members' caption="Suchparameter" %} + +Wenn du mit der Vorschau zufrieden bist, klicke auf "weiter". + +## Standard-Gruppierungsnummer + +Für einige Prozesse benötigt Adrema die Standard-Gruppierungsnummer. Dies ist i.d.R. die Gruppierungsnummer deiner lokalen Gruppierung die du verwalten willst (z.B. dein Stamm). + +{% include imgcap.html img='init-default-groupid' caption="Standard-Gruppierungsnummer" %} + +## 4. Initialisierung starten + +Danach führt Adrema im Hintergrund selbstständig einen ersten Abgleich durch. Dies kann je nach Datenmenge einige Minuten bis Stunden dauern. + +{% include imgcap.html img='init-confirm' caption="Einrichtung abschließen" %} + +Du wirst danach ins Dashboard weitergeleitet. Nach und nach wird sich die Mitgliederliste dann mit den Mitgliedern füllen, solange bis alles abgerufen ist. diff --git a/doc/page/firststeps/index.md b/doc/page/firststeps/index.md new file mode 100644 index 00000000..3ec4e0ab --- /dev/null +++ b/doc/page/firststeps/index.md @@ -0,0 +1,11 @@ +--- +layout: page +title: Erste Schritte +has_children: true +nav_order: 1 +--- + +# Erste Schritte + +Hier findest du Hinweise zur Grundeinrichtung von Adrema. + diff --git a/doc/page/firststeps/install.md b/doc/page/firststeps/install.md new file mode 100644 index 00000000..636c22fc --- /dev/null +++ b/doc/page/firststeps/install.md @@ -0,0 +1,65 @@ +--- +layout: page +title: Installation +parent: Erste Schritte +nav_order: 1 +--- + + +# Installation + +Adrema ist eine Web-Applikation, die auf einem Webserver installiert werden kann. Die Installation mit Docker wird empfohlen, da hier bereits alle notwendigen Dienste mit installiert werden. + +{: .warning } +Für die Installation sind Grundkenntnisse im Umgang mit Docker und / oder Server-Umgebungen erforderlich. Wenn du hier Hilfe benötigst, [kontaktiere uns]({% link kontakt.md %}). + +## Mindestanforderungen + +Die Mindestanforderungen sind größtenteils die Anforderungen vom [Laravel Framework](https://laravel.com/docs/10.x/deployment#server-requirements). Diese (plus einige Extra-Anforderungen) sind hier kurz ausgeführt: + + +{: .block-title } +> Anforderungen +> +> PHP >= 8.1 +> Ctype PHP Extension +> cURL PHP Extension +> DOM PHP Extension +> Fileinfo PHP Extension +> Filter PHP Extension +> Hash PHP Extension +> Mbstring PHP Extension +> OpenSSL PHP Extension +> PCRE PHP Extension +> PDO PHP Extension +> Session PHP Extension +> Tokenizer PHP Extension +> XML PHP Extensionnother paragraph +> Texlive mit fonts-extra (pdflatex & xelatex) +> rsync + +## Installation mit Docker + +```bash +git submodule update --init # Submodules updaten +cp .app.env.example .app.env # Example env erstellen: +docker-compose build # Container bauen +docker-compose run php php artisan key:generate --show # Key generieren + +# Ersetze nun "YOUR_APP_KEY" in .app.env mit dem generierten Key (base64:qzX....). +# Führe nun den DB Container aus, um eine erste Version der Datenbank zu erstellen. +docker-compose up db -d +docker-compose run php php artisan migrate --seed # Migrations ausführen +docker-compose stop # Alles stoppen, dann alles neu starten +docker-compose up -d +``` + +Nun kannst du auf localhost:8000 die App öffnen, einen LoadBalancer wie nginx verwenden, den Port mit CLI Optionen ändern, etc. + +## Standard Login + +Wenn du die Seeder ausführst (``--seed``, siehe oben), wird ein Benutzer mit folgenden Zugangsdaten erstellt: + +* E-Mail-Adresse: admin@example.com +* Passwort: admin + diff --git a/doc/index.md b/doc/page/index.md similarity index 88% rename from doc/index.md rename to doc/page/index.md index 5a334c11..652a8fe2 100644 --- a/doc/index.md +++ b/doc/page/index.md @@ -1,11 +1,14 @@ --- layout: home +nav_order: 0 --- # Willkommen bei Adrema Adrema ist eine Applikation, die die Verwaltung von Mitgliedern in der DPSG vereinfachen soll. +{% include imgcap.html img='member' caption="Mitglieder-Übersicht" %} + Insbesondere soll dabei möglichst auf eine direkte Interaktion mit NaMi verzichtet werden. Sämtliche Änderungen die du in Adrema an deinen Mitgliedern vornimmst werden automatisch in NaMi übernommen und dort aktualisiert. diff --git a/doc/page/kontakt.md b/doc/page/kontakt.md new file mode 100644 index 00000000..b8b121e3 --- /dev/null +++ b/doc/page/kontakt.md @@ -0,0 +1,17 @@ +--- +layout: page +title: Kontakt +nav_order: 5 +--- + +# Kontakt + +Wenn du Hilfe bei der Einrichtung brauchst, Rückfragen, Verbesserungsvorschläge oder etwas ähnliches hast, dann kontaktiere mich einfach. + +## E-Mail + +[philipp@zoomyboy.de](mailto:philipp@zoomyboy.de) + +## Matrix + +@philipp:zoomyboy.de diff --git a/doc/version.md b/doc/page/version.md similarity index 99% rename from doc/version.md rename to doc/page/version.md index 29067588..4fc894b4 100644 --- a/doc/version.md +++ b/doc/page/version.md @@ -1,6 +1,7 @@ --- layout: page title: Versionierung +nav_order: 4 --- # Versionierung