Update README.md

2026-08-08 21:17:57 +02:00
1 parent 8d7bc82fef
commit 0b52c0cde4
@@ -0,0 +1,578 @@
 # 🌐 Joplin Web – Self-Hosted Docker
 Eine selbst gehostete **Joplin Web App**, die den offiziellen Joplin-Web-Client aus dem Joplin-Quellcode baut und anschließend über einen schlanken nginx-Container bereitstellt.
 Die Web-App kann mit einem vorhandenen **Joplin Server** synchronisiert werden und ermöglicht den Zugriff auf Joplin-Notizen direkt über den Browser.
 > ⚠️ Joplin Web befindet sich noch in Entwicklung/Beta. Vor produktivem Einsatz sollten Backups der Joplin-Daten vorhanden sein.
 ---
 ## ✨ Features
 - 🌐 Joplin direkt im Webbrowser
 - 🐳 Vollständig über Docker betreibbar
 - 🔄 Synchronisation mit einem eigenen Joplin Server
 - 🔐 Betrieb über HTTPS / Reverse Proxy
 - 🗄️ Browserbasierter lokaler Speicher
 - 📎 Unterstützung der Joplin-Synchronisation
 - 🚀 Fertiges Docker-Image kann über eine Container Registry verteilt werden
 - 🛡️ Zusätzlicher Zugriffsschutz über den Reverse Proxy möglich
 ---
 ## 🏗️ Aufbau
 ```text
                        ┌──────────────────────┐
                        │       Browser        │
                        │ Firefox / Chrome ... │
                        └──────────┬───────────┘
                                   │
                                 HTTPS
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │    Reverse Proxy     │
                        │ nginx / NPM / etc.   │
                        └──────────┬───────────┘
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │     Joplin Web       │
                        │   nginx + Web App    │
                        │      Port 3000       │
                        └──────────┬───────────┘
                                   │
                              HTTPS / API
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │    Joplin Server     │
                        │   Sync + Benutzer    │
                        └──────────────────────┘
 ```
 ---
 # 📁 Projektstruktur
 ```text
 joplin-web/
 ├── Dockerfile
 ├── docker-compose.yml
 ├── nginx.conf
 ├── README.md
 └── .gitignore
 ```
 ---
 # 🚀 Installation
 ## Variante 1 – Fertiges Container-Image
 Wenn das Image bereits in einer Container Registry vorhanden ist, wird auf dem Zielserver kein Joplin-Build benötigt.
 Beispiel:
 ```yaml
 services:
  joplin-web:
    image: gitea.example.com/username/joplin-web:latest
    container_name: joplin-web
    restart: unless-stopped
    ports:
      - "3000:80"
    security_opt:
      - no-new-privileges:true
 ```
 Container starten:
 ```bash
 docker compose pull
 docker compose up -d
 ```
 Status prüfen:
 ```bash
 docker compose ps
 ```
 Logs anzeigen:
 ```bash
 docker logs -f joplin-web
 ```
 Die Web-App ist anschließend lokal unter folgendem Port erreichbar:
 ```text
 http://SERVER-IP:3000
 ```
 > Für den produktiven Betrieb sollte Joplin Web über **HTTPS** bereitgestellt werden.
 ---
 # 🔨 Variante 2 – Image selbst bauen
 Repository klonen:
 ```bash
 git clone https://gitea.example.com/username/joplin-web.git
 cd joplin-web
 ```
 Image bauen:
 ```bash
 docker compose build --no-cache --progress=plain
 ```
 Anschließend starten:
 ```bash
 docker compose up -d
 ```
 Status prüfen:
 ```bash
 docker compose ps
 ```
 ---
 # 🐳 Docker Image
 Das Docker-Image wird in mehreren Stufen gebaut.
 ## Builder
 Im ersten Schritt wird der offizielle Joplin-Quellcode geladen und die Web-App gebaut.
 Dabei werden unter anderem verwendet:
 - Devbox
 - Nix
 - Node.js
 - Yarn
 - Joplin Source
 - Joplin Mobile Web Build
 Der Web-Build wird anschließend aus folgendem Verzeichnis übernommen:
 ```text
 packages/app-mobile/web/dist
 ```
 ## Runtime
 Der eigentliche produktive Container benötigt die Build-Umgebung nicht mehr.
 Das fertige Web-Frontend wird über:
 ```text
 nginx
 ```
 bereitgestellt.
 Dadurch bleibt der laufende Container wesentlich kleiner als die Build-Umgebung.
 ---
 # 🔐 HTTPS
 Joplin Web sollte nicht dauerhaft über eine unverschlüsselte HTTP-Verbindung verwendet werden.
 Bestimmte Browser-APIs, die Joplin Web benötigt, stehen nur in einem **Secure Context** zur Verfügung.
 Empfohlen:
 ```text
 https://joplin-web.example.com
 ```
 Der Reverse Proxy kann intern weiterhin auf:
 ```text
 http://JOPLIN-WEB-IP:3000
 ```
 weiterleiten.
 ---
 # 🧠 Cross-Origin Isolation
 Für bestimmte Browser-Funktionen werden folgende HTTP-Header ausgeliefert:
 ```text
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 Cross-Origin-Resource-Policy: same-origin
 ```
 Überprüfen:
 ```bash
 curl -I http://127.0.0.1:3000
 ```
 Beispiel:
 ```text
 HTTP/1.1 200 OK
 Server: nginx
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 Cross-Origin-Resource-Policy: same-origin
 ```
 Im Browser kann zusätzlich geprüft werden:
 ```javascript
 window.isSecureContext
 ```
 und:
 ```javascript
 crossOriginIsolated
 ```
 ---
 # 🔄 Verbindung mit Joplin Server
 In Joplin Web unter der Synchronisationskonfiguration als Ziel **Joplin Server** auswählen.
 Als Server-URL wird ausschließlich die Basis-URL verwendet:
 ```text
 https://joplin.example.com
 ```
 Nicht:
 ```text
 https://joplin.example.com/api
 ```
 und nicht:
 ```text
 https://joplin.example.com/login
 ```
 Anschließend die Zugangsdaten des Joplin-Benutzers eintragen.
 ---
 # 🌍 CORS bei eigenem Joplin Server
 Wenn Joplin Web und Joplin Server unterschiedliche Domains verwenden, muss der Browser Cross-Origin-Anfragen zulassen.
 Beispiel:
 ```text
 Joplin Web:
 https://joplin-web.example.com
 Joplin Server:
 https://joplin.example.com
 ```
 Ohne entsprechende Konfiguration können Fehler auftreten wie:
 ```text
 Blocked by CORS policy
 ```
 oder:
 ```text
 Cross-Origin Request Blocked
 ```
 ## Beispiel für nginx / Nginx Proxy Manager
 Auf dem Reverse Proxy des **Joplin Servers**:
 ```nginx
 proxy_hide_header Access-Control-Allow-Origin;
 proxy_hide_header Access-Control-Allow-Methods;
 proxy_hide_header Access-Control-Allow-Headers;
 more_set_headers "Access-Control-Allow-Origin: https://joplin-web.example.com";
 more_set_headers "Access-Control-Allow-Methods: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS";
 more_set_headers "Access-Control-Allow-Headers: Content-Type, Authorization, X-API-MIN-VERSION, X-API-AUTH";
 more_set_headers "Vary: Origin";
 ```
 > Die Domain muss an die eigene Joplin-Web-Adresse angepasst werden.
 ---
 ## CORS testen
 Preflight-Anfrage:
 ```bash
 curl -i -X OPTIONS \
  -H "Origin: https://joplin-web.example.com" \
  -H "Access-Control-Request-Method: PUT" \
  -H "Access-Control-Request-Headers: content-type,x-api-min-version,x-api-auth" \
  https://joplin.example.com/api/items/root:/testing.txt:/content
 ```
 Die Antwort sollte unter anderem enthalten:
 ```text
 Access-Control-Allow-Origin: https://joplin-web.example.com
 Access-Control-Allow-Methods:
 GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
 Access-Control-Allow-Headers:
 Content-Type, Authorization, X-API-MIN-VERSION, X-API-AUTH
 ```
 ---
 # 🔒 Zusätzlicher Zugriffsschutz
 Da die Web-App grundsätzlich über ihre URL erreichbar ist, empfiehlt sich ein zusätzlicher Schutz auf Reverse-Proxy-Ebene.
 Mögliche Lösungen:
 - HTTP Basic Authentication
 - Nginx Proxy Manager Access Lists
 - Authelia
 - Authentik
 - VPN / WireGuard / NetBird
 Die Architektur sieht dann beispielsweise so aus:
 ```text
 Internet
   │
   ▼
 Reverse Proxy
   │
   ├── Authentifizierung
   │
   ▼
 Joplin Web
   │
   ▼
 Joplin Server
 ```
 Die eigentlichen Joplin-Zugangsdaten werden weiterhin für die Synchronisation mit dem Joplin Server verwendet.
 ---
 # 🔄 Update
 ## Bei Verwendung eines fertigen Images
 ```bash
 docker compose pull
 docker compose up -d
 ```
 Nicht mehr verwendete Images können anschließend entfernt werden:
 ```bash
 docker image prune
 ```
 ---
 ## Bei lokalem Build
 Repository aktualisieren:
 ```bash
 git pull
 ```
 Danach neu bauen:
 ```bash
 docker compose build --no-cache
 docker compose up -d
 ```
 ---
 # 📦 Image in eine Gitea Container Registry pushen
 Zunächst anmelden:
 ```bash
 docker login gitea.example.com
 ```
 Image taggen:
 ```bash
 docker tag joplin-web-joplin-web:latest \
  gitea.example.com/username/joplin-web:latest
 ```
 Danach:
 ```bash
 docker push gitea.example.com/username/joplin-web:latest
 ```
 Auf einem anderen Docker-Server genügt anschließend:
 ```bash
 docker login gitea.example.com
 docker compose pull
 docker compose up -d
 ```
 Damit muss Joplin auf dem Zielserver **nicht erneut aus dem Quellcode gebaut werden**.
 ---
 # 🧹 Nützliche Docker-Befehle
 Container anzeigen:
 ```bash
 docker compose ps
 ```
 Logs:
 ```bash
 docker logs -f joplin-web
 ```
 Container neu starten:
 ```bash
 docker compose restart
 ```
 Container stoppen:
 ```bash
 docker compose down
 ```
 Container starten:
 ```bash
 docker compose up -d
 ```
 Image neu bauen:
 ```bash
 docker compose build --no-cache
 ```
 ---
 # 🛠️ Fehlerbehebung
 ## Web-App lädt nicht
 Container prüfen:
 ```bash
 docker compose ps
 ```
 Logs:
 ```bash
 docker logs joplin-web --tail 100
 ```
 Webserver lokal testen:
 ```bash
 curl -I http://127.0.0.1:3000
 ```
 ---
 ## Synchronisation schlägt fehl
 Browser-Entwicklertools öffnen und unter **Console** bzw. **Network** nach Fehlern suchen.
 Häufige Ursachen:
 - falsche Joplin-Server-URL
 - CORS
 - fehlender `X-API-AUTH` Header
 - Reverse-Proxy-Konfiguration
 - Zertifikatsprobleme
 ---
 ## Browser zeigt alten Stand
 Joplin Web verwendet Browser-Speicher und Service Worker.
 Bei Problemen:
 1. Alle Joplin-Web-Tabs schließen.
 2. Website-Daten der Joplin-Web-Domain löschen.
 3. Browser vollständig schließen.
 4. Browser neu starten.
 5. Joplin Web erneut öffnen.
 ---
 # ⚠️ Hinweise
 Joplin Web speichert lokale Client-Daten im Browser.
 Daher gilt:
 - Browserdaten nicht unüberlegt löschen.
 - Synchronisation vor größeren Änderungen vollständig durchführen.
 - Regelmäßige Backups des Joplin Servers erstellen.
 - Die Web-App möglichst nur über HTTPS betreiben.
 - Für öffentlich erreichbare Installationen zusätzlichen Zugriffsschutz verwenden.
 ---
 # 🔗 Links
 - Joplin: https://joplinapp.org/
 - Joplin GitHub: https://github.com/laurent22/joplin
 - Joplin Build Documentation: https://joplinapp.org/help/dev/BUILD/
 - Docker: https://www.docker.com/
 - Gitea: https://about.gitea.com/
 ---
 # 📜 Lizenz
 Dieses Repository enthält die Docker-/Deployment-Konfiguration für Joplin Web.
 Joplin selbst ist ein eigenständiges Open-Source-Projekt. Für Joplin gelten die Lizenzbedingungen des offiziellen Joplin-Projekts.
 ---
 ## ❤️ Credits
 [Joplin](https://joplinapp.org/) wird von Laurent Cozic und der Joplin-Community entwickelt.
 Dieses Repository stellt lediglich eine Docker-basierte Möglichkeit bereit, den Joplin-Web-Client selbst zu bauen und zu hosten.