Mirror of https://forge.levinkeller.de/levin/dorfarchiv.git
6b83fb2a60d74f2dbca3c0b90e306d5d3a19c62b
| 1 | # Geschützte Dokumentations-Vorlage |
| 2 | |
| 3 | Eine moderne Vorlage für die Erstellung **geschützter Dokumentations-Websites**, die die Leistungsfähigkeit von [Docusaurus](https://docusaurus.io/) mit robuster Authentifizierung und Zugriffskontrolle kombiniert. |
| 4 | |
| 5 |  |
| 6 |  |
| 7 |  |
| 8 |  |
| 9 | |
| 10 | ## 🎯 Was ist das? |
| 11 | |
| 12 | Diese Vorlage bietet eine vollständige Lösung für die Erstellung von Dokumentations-Websites, die nur für authentifizierte Benutzer zugänglich sind. Perfekt geeignet für: |
| 13 | |
| 14 | - **Interne Unternehmensdokumentation**, die nur für Mitarbeiter zugänglich sein soll |
| 15 | - **Mitglieder-exklusive Inhalte** für Organisationen, Communities oder Premium-Nutzer |
| 16 | - **Private API-Dokumentation**, die Benutzerauthentifizierung erfordert |
| 17 | - **Kundenportale** mit eingeschränktem Zugriff für bestimmte Benutzergruppen |
| 18 | - **Bildungsinhalte** mit Zugriffskontrolle basierend auf Anmeldung oder Mitgliedschaft |
| 19 | |
| 20 | ## 🏗️ Wie es funktioniert |
| 21 | |
| 22 | Die Vorlage besteht aus zwei Hauptkomponenten, die zusammenarbeiten: |
| 23 | |
| 24 | ### 1. Dokumentations-Website (Docusaurus) |
| 25 | - Erstellt mit **Docusaurus 3.8**, einem modernen statischen Website-Generator |
| 26 | - Unterstützt **Markdown** für einfache Inhaltserstellung |
| 27 | - Bietet **Internationalisierungs**-Support (i18n) |
| 28 | - Beinhaltet **Blog-Funktionalität** und **Versionierung** |
| 29 | - Responsives Design mit Dunkel-/Hell-Modus-Unterstützung |
| 30 | |
| 31 | ### 2. Authentifizierungs-Server (Node.js + Express) |
| 32 | - **OAuth-Authentifizierung** über GitHub, Google und andere Anbieter |
| 33 | - **PocketBase**-Integration für Benutzerverwaltung und Zugriffskontrolle |
| 34 | - **Gruppenbasierte Zugriffskontrolle** - Benutzer müssen Mitglieder bestimmter Gruppen sein |
| 35 | - **Session-Management** mit sicheren Cookies |
| 36 | - **Mehrsprachige Unterstützung** (deutsche und englische Login-Seiten) |
| 37 | |
| 38 | ### Authentifizierungs-Ablauf |
| 39 | 1. Benutzer besucht die Dokumentations-Website |
| 40 | 2. Server prüft auf gültiges Authentifizierungs-Cookie |
| 41 | 3. Falls nicht authentifiziert, wird der Benutzer zur Login-Seite weitergeleitet |
| 42 | 4. Benutzer authentifiziert sich über OAuth-Anbieter (GitHub, Google, etc.) |
| 43 | 5. Server überprüft, ob Benutzer Mitglied der erforderlichen Gruppe(n) ist |
| 44 | 6. Falls autorisiert, erhält der Benutzer Zugriff auf die geschützte Dokumentation |
| 45 | |
| 46 | ## 🚀 Schnellstart |
| 47 | |
| 48 | ### Voraussetzungen |
| 49 | - **Node.js 18+** |
| 50 | - **Docker** (optional, für containerisierte Bereitstellung) |
| 51 | - **PocketBase-Instanz** (für Benutzerverwaltung) |
| 52 | |
| 53 | ### 1. Klonen und Installieren |
| 54 | ```bash |
| 55 | git clone <ihr-fork-dieses-repos> |
| 56 | cd protected-docs-template |
| 57 | npm install |
| 58 | ``` |
| 59 | |
| 60 | ### 2. Umgebung Konfigurieren |
| 61 | Erstellen Sie eine `.env.local`-Datei im Stammverzeichnis: |
| 62 | ```env |
| 63 | POCKETBASE_URL=https://ihre-pocketbase-instanz.com |
| 64 | POCKETBASE_GROUP=ihr-gruppen-name |
| 65 | PORT=8000 |
| 66 | ``` |
| 67 | |
| 68 | ### 3. PocketBase Einrichten |
| 69 | 1. Erstellen Sie eine PocketBase-Instanz (selbst gehostet oder Cloud) |
| 70 | 2. Erstellen Sie eine `groups`-Sammlung mit `user_id` und `ihr-gruppen-name` Feldern |
| 71 | 3. Konfigurieren Sie OAuth-Anbieter (GitHub, Google, etc.) |
| 72 | 4. Fügen Sie Benutzer zu den entsprechenden Gruppen hinzu |
| 73 | |
| 74 | ### 4. Ihre Dokumentation Anpassen |
| 75 | Navigieren Sie zum `website/`-Verzeichnis und: |
| 76 | ```bash |
| 77 | cd website |
| 78 | # Bearbeiten Sie Ihre Dokumentationsdateien in docs/ |
| 79 | # Passen Sie die Website-Konfiguration in docusaurus.config.ts an |
| 80 | # Fügen Sie Ihr Branding, Farben und Inhalte hinzu |
| 81 | ``` |
| 82 | |
| 83 | ### 5. Erstellen und Ausführen |
| 84 | |
| 85 | #### Entwicklungsmodus |
| 86 | ```bash |
| 87 | # Website-Entwicklungsserver starten |
| 88 | cd website |
| 89 | npm run start |
| 90 | |
| 91 | # In einem anderen Terminal den Auth-Server starten |
| 92 | cd server |
| 93 | npm run start |
| 94 | ``` |
| 95 | |
| 96 | #### Produktionsmodus |
| 97 | ```bash |
| 98 | # Website erstellen |
| 99 | cd website |
| 100 | npm run build |
| 101 | |
| 102 | # Produktionsserver starten |
| 103 | cd server |
| 104 | npm run start |
| 105 | ``` |
| 106 | |
| 107 | #### Docker-Bereitstellung |
| 108 | ```bash |
| 109 | docker compose up --build |
| 110 | ``` |
| 111 | |
| 112 | Die Anwendung ist unter `http://localhost:8000` verfügbar |
| 113 | |
| 114 | ## 📁 Projekt-Struktur |
| 115 | |
| 116 | ``` |
| 117 | protected-docs-template/ |
| 118 | ├── website/ # Docusaurus-Dokumentations-Website |
| 119 | │ ├── docs/ # Dokumentationsinhalte (Markdown-Dateien) |
| 120 | │ ├── blog/ # Blog-Beiträge |
| 121 | │ ├── src/ # React-Komponenten und Seiten |
| 122 | │ ├── static/ # Statische Assets |
| 123 | │ └── docusaurus.config.ts # Website-Konfiguration |
| 124 | ├── server/ # Authentifizierungs-Server |
| 125 | │ ├── index.ts # Haupt-Server-Datei |
| 126 | │ └── views/ # Login-Seiten-Vorlagen |
| 127 | ├── Dockerfile # Container-Konfiguration |
| 128 | ├── docker-compose.yaml # Multi-Container-Setup |
| 129 | └── package.json # Workspace-Konfiguration |
| 130 | ``` |
| 131 | |
| 132 | ## 🔧 Konfiguration |
| 133 | |
| 134 | ### Authentifizierungs-Anbieter |
| 135 | Das System unterstützt mehrere OAuth-Anbieter über PocketBase: |
| 136 | - **GitHub** (Standard) |
| 137 | - **Google** (Standard) |
| 138 | - **Microsoft** |
| 139 | - **Facebook** |
| 140 | - **GitLab** |
| 141 | - **Discord** |
| 142 | - **Spotify** |
| 143 | - Und viele mehr... |
| 144 | |
| 145 | Um neue Anbieter hinzuzufügen, konfigurieren Sie diese in Ihrem PocketBase-Admin-Panel. |
| 146 | |
| 147 | ### Zugriffskontrolle |
| 148 | Benutzer müssen Mitglieder einer bestimmten Gruppe sein, um auf die Dokumentation zugreifen zu können. Konfigurieren Sie dies in Ihrer `.env.local`: |
| 149 | ```env |
| 150 | POCKETBASE_GROUP=mitarbeiter # Nur Benutzer in der "mitarbeiter"-Gruppe können zugreifen |
| 151 | ``` |
| 152 | |
| 153 | ### Internationalisierung |
| 154 | Die Vorlage beinhaltet standardmäßig deutsche Sprachunterstützung. Um weitere Sprachen hinzuzufügen: |
| 155 | |
| 156 | 1. Aktualisieren Sie `docusaurus.config.ts`: |
| 157 | ```typescript |
| 158 | i18n: { |
| 159 | defaultLocale: 'de', |
| 160 | locales: ['de', 'en', 'fr'], // Fügen Sie Ihre Sprachen hinzu |
| 161 | }, |
| 162 | ``` |
| 163 | |
| 164 | 2. Erstellen Sie Übersetzungsdateien in `website/i18n/` |
| 165 | |
| 166 | ### Anpassung |
| 167 | - **Branding**: Bearbeiten Sie `website/docusaurus.config.ts` und `website/src/css/custom.css` |
| 168 | - **Inhalte**: Fügen Sie Ihre Dokumentation zu `website/docs/` hinzu |
| 169 | - **Login-Seiten**: Passen Sie `server/views/login.ejs` und `server/views/not_a_member.ejs` an |
| 170 | |
| 171 | ## 🎨 Anwendungsfälle |
| 172 | |
| 173 | ### Interne Unternehmensdokumentation |
| 174 | Perfekt für Unternehmen, die interne Dokumentation, Prozesse oder Wissensdatenbanken nur mit Mitarbeitern teilen müssen. |
| 175 | |
| 176 | ```env |
| 177 | POCKETBASE_GROUP=mitarbeiter |
| 178 | ``` |
| 179 | |
| 180 | ### Kundenportale |
| 181 | Erstellen Sie Dokumentationsportale für spezifische Kunden oder Kundensegmente. |
| 182 | |
| 183 | ```env |
| 184 | POCKETBASE_GROUP=premium_kunden |
| 185 | ``` |
| 186 | |
| 187 | ### Bildungsplattformen |
| 188 | Stellen Sie Kursmaterialien oder Lernressourcen für eingeschriebene Studenten oder Mitglieder bereit. |
| 189 | |
| 190 | ```env |
| 191 | POCKETBASE_GROUP=kurs_teilnehmer |
| 192 | ``` |
| 193 | |
| 194 | ### API-Dokumentation |
| 195 | Teilen Sie private API-Dokumentation mit autorisierten Entwicklern oder Partnern. |
| 196 | |
| 197 | ```env |
| 198 | POCKETBASE_GROUP=api_partner |
| 199 | ``` |
| 200 | |
| 201 | ## 🛠️ Entwicklung |
| 202 | |
| 203 | ### Neue Inhalte Hinzufügen |
| 204 | 1. Erstellen Sie Markdown-Dateien in `website/docs/` |
| 205 | 2. Aktualisieren Sie `website/sidebars.ts` falls nötig |
| 206 | 3. Fügen Sie Blog-Beiträge zu `website/blog/` hinzu |
| 207 | |
| 208 | ### Authentifizierung Anpassen |
| 209 | - Ändern Sie `server/index.ts` um die Authentifizierungslogik zu modifizieren |
| 210 | - Aktualisieren Sie Login-Vorlagen in `server/views/` |
| 211 | - Konfigurieren Sie zusätzliche OAuth-Anbieter in PocketBase |
| 212 | |
| 213 | ### Styling und Theming |
| 214 | - Bearbeiten Sie `website/src/css/custom.css` für globale Styles |
| 215 | - Ändern Sie `website/docusaurus.config.ts` für Theme-Konfiguration |
| 216 | - Erstellen Sie benutzerdefinierte React-Komponenten in `website/src/components/` |
| 217 | |
| 218 | ## 🚀 Bereitstellung |
| 219 | |
| 220 | ### Docker (Empfohlen) |
| 221 | ```bash |
| 222 | docker compose up --build -d |
| 223 | ``` |
| 224 | |
| 225 | ### Manuelle Bereitstellung |
| 226 | 1. Website erstellen: `cd website && npm run build` |
| 227 | 2. Server mit erstellten Dateien bereitstellen |
| 228 | 3. Umgebungsvariablen konfigurieren |
| 229 | 4. Reverse Proxy einrichten (nginx, Apache, etc.) |
| 230 | |
| 231 | ### Cloud-Plattformen |
| 232 | Die Vorlage funktioniert gut mit: |
| 233 | - **Vercel** (für die Dokumentations-Website) |
| 234 | - **Railway** / **Heroku** (für den Auth-Server) |
| 235 | - **Digital Ocean** / **AWS** / **Google Cloud** (vollständiger Stack) |
| 236 | |
| 237 | ## 🔒 Sicherheitsfeatures |
| 238 | |
| 239 | - **Nur OAuth-Authentifizierung** - keine Passwort-Speicherung erforderlich |
| 240 | - **Gruppenbasierte Zugriffskontrolle** - feingliedrige Berechtigungen |
| 241 | - **Sicheres Session-Management** - httpOnly-Cookies mit ordnungsgemäßen Einstellungen |
| 242 | - **CSRF-Schutz** - in den Authentifizierungsablauf integriert |
| 243 | - **Regelmäßige Sicherheitsupdates** - basierend auf gewarteten Abhängigkeiten |
| 244 | |
| 245 | ## 📝 Lizenz |
| 246 | |
| 247 | Diese Vorlage ist Open Source und unter der [MIT-Lizenz](LICENSE) verfügbar. |
| 248 | |
| 249 | ## 🤝 Mitwirken |
| 250 | |
| 251 | 1. Repository forken |
| 252 | 2. Feature-Branch erstellen |
| 253 | 3. Änderungen vornehmen |
| 254 | 4. Tests hinzufügen falls zutreffend |
| 255 | 5. Pull Request einreichen |
| 256 | |
| 257 | ## 📞 Support |
| 258 | |
| 259 | - **Issues**: Melden Sie Bugs oder fordern Sie Features über GitHub Issues an |
| 260 | - **Diskussionen**: Nehmen Sie an Community-Diskussionen in GitHub Discussions teil |
| 261 | - **Dokumentation**: Prüfen Sie die [Docusaurus-Dokumentation](https://docusaurus.io/docs) für Website-Anpassungen |
| 262 | |
| 263 | ## 🏷️ Version |
| 264 | |
| 265 | Aktuelle Version: **1.0.0** |
| 266 | |
| 267 | Erstellt mit: |
| 268 | - Docusaurus 3.8.1 |
| 269 | - Node.js 18+ |
| 270 | - PocketBase 0.26 |
| 271 | - Express 4.21 |
| 272 | - TypeScript 5.6 |
| 273 | |
| 274 | --- |
| 275 | |
| 276 | **Mit ❤️ für die Entwickler-Community gemacht** |