Skip to content
This repository has been archived by the owner on Apr 25, 2022. It is now read-only.

Serveradministration

KIMBtech edited this page Aug 28, 2019 · 14 revisions

Installation

KIMB-Notes wurde für PHP 7 entwickelt und speichert seine Datein in einer Verzeichnisstruktur mittels JSON-Dateien.

  1. Unter Releases kann die aktuellste Version von KIMB-Notes-Server heruntergeladen werden.
    Wählen Sie einfach die ZIP oder TarGz und entpacken Sie diese auf dem gewünschten Webserver.
    Im Folgen gehen wir davon aus, dass der Ordner mit dem Inhalt des Archivs unter https://notes.example.com/ verfügbar ist.
  2. Rufen Sie https://notes.example.com/install/ auf und folgen Sie den Anweisungen.
    1. Ihnen wird vorgeschlagen, das Tool unter https://notes.example.com/system/ verfügbar zu machen. Sie können hier auch https://notes.example.com/ angeben, dann müssen Sie nach der Installation die Dateien aus /system/ nach / verschieben.
    2. Nachdem die Konfiguration geschrieben wurde, müssen Sie noch einen ersten Administrator erstellen. Wählen sie einen eigenen Username und ein gutes Passwort.
  3. Jetzt ist KIMB-Notes betriebsbereit und kann unter der gewählten URL aufgerufen werden.
  4. Zum Abschluss sollten Sie das Verzeichnis /install/ löschen.
    (Der Installer ist zwar auch so gesperrt, aber er wird nicht weiter benötigt!)
    Es bietet sich auch an das Verzeichnis build zu löschen.
  5. Wenn Sie wie in 2.i. vorgeschlagen https://notes.example.com/ als URL gewählt haben, dann müssen noch alle Inhalte des Ordners /system/ nach / verschoben werden, der leere Ordner /system/ kann gelöscht werden.
  6. Die Verzeichnisse data und php (unter system) dürfen nicht aus dem Web erreichbar sein, bei Nutzung eines Apache-Servers werden sie automatisch mittels .htaccess gesperrt. Bei anderen Servern muss dies manuell geschehen!

Für die Entwicklung können Sie einfach dieses Repository clonen und anschließend mittles php -S localhost:8000 einen Server starten.
KIMB-Notes finden Sie dann unter http://localhost:8000/system/

Docker Installation

Es gibt ein Docker Image, welches KIMB-Notes mit PHP und einem Nginx Server beinhaltet.

  1. Die docker-compose.yml herunterladen.
  2. Die Parameter anpassen. Für die Konfiguration wird environment genutzt:
    • CONF_domain Die Domain unter der KIMB-Notes erreichbar sein wird, z.B. http://localhost:8080.
    • CONF_impressum_name Der Name für einen Link der unten auf der Seite erscheint, z.B. Impressum.
    • CONF_impressum_url Die URL auf den der Link unten auf der Seite zeigen soll.
    • CONF_markdown_info Soll ein Link auf die Markdown-Hinweisseite angezeigt werden (true, false).
    • CONF_syspoll Abstand in Sekunden in denen der Sever nach Änderungen an der Notiz gefragt wird, z.B. 30.
    • USER_name (optional) Ein Username für den initialen Administrator (Account wird neu erstellt, falls nicht vorhanden).
    • USER_password (optional) Ein Passwort für den initialen Administrator (Ist der Account vorhanden, wir das Passwort neu geschrieben).

      Es ist sinnvoll die USER_* Variablen zu entfernen sobald der User erstellt wurde.
      Sollte es zu einer Fehlermeldung fopen(/php-code/data/user/userslist.json.lock) failed beim Start des Container kommen, bitte mit docker-compose up --force-recreate erneut versuchen.

  3. KIMB-Notes sollte unter der gewählten URL bzw. dem gewählten Port verfügbar sein.
  4. Updates können einfach durch pullen des aktuellen Images durchgeführt werden.

Eigene Builds und Entwicklung

Während der Entwicklung werden natürlich JSON-Dateien angelegt und verändert. Weiterhin wird an den CSS-, JS- und PHP-Dateien Code hinzugefügt und entfernt. Bei den JS- und CSS-Dateien bietet es sich an an den Dateien mit Endung .dev.js, .dev.css zu arbeiten.

Werden neue Dateien hinzugefügt, dann müssen diese in der AppCache.php eingetragen werden. Und evtl. auch für den Buildvorgang gelistet werden.

Wenn alles im Entwicklungsmodus funktioniert, dann können über das Build-Skript im Ordner build die JSON-Dateien zurückgesetzt und die CSS- und JS-Dateien minimiert und zusammengefügt werden. (Eine Readme zum NodeJS-Skript befindet sich dort.)

User verwalten

Loggen Sie sich als Administrator wie ein ganz normaler User ein. Neben dem Icon für den Useraccountmanager finden Sie oben rechts jetzt auch ein Icon für den Adminstrationsdialog (die Zange).

In diesem Dialog werden Ihnen alle User des System, mit UserID, Username und dem Adminstatus, angezeigt. Sie haben die Möglichkeit jeden dieser User zu löschen. Dabei wird nur der Account (Username, Passwort, Authentifikationslinks) gelöscht, die Notizen des Users bleiben weiterhin auf dem Server. (Sie können dann aber nur noch manuell wiederhergestellt werden.)

Weiterhin können Sie unter der Tabelle auch neue User hinzufügen. Neben Username und Passwort können Sie noch bestimmen, ob der neue User auch Adminstratorrechte haben soll. (Es gibt keine verschiedenen Adminstratorlevel und Änderungen der Rechte und des Usernames sind nur manuell möglich.)

Updates

Es gibt keine automatische Updatefunktion, sofern eine neue Version verfügbar ist und keine Hinweise zu Update angegeben werden, ist folgende Methode möglich:

  1. Erstellen Sie ein vollständiges Backup des Ordners <webspace>/<notes>/data/.
  2. Löschen Sie alle Ordner und Dateien in <webspace>/<notes>/.
  3. Entpacken Sie die neue Version nach <webspace>/<notes>/.
  4. Ersetzen Sie den entpackten Ordner <webspace>/<notes>/data/ durch ihr Backup.
    • Dateien überscheiben

Bei Updates an der Datenstruktur unter data ist KIMB-Notes entweder abwärtskompatibel zur alten Datenstruktur oder es wird ein Updateskript mitgeliefert, welches in den Hinweisen zur neuen Version angeben wird.

Manuelle Änderungen an der Datenstruktur

Achtung: Machen Sie immer ein Backup der Daten, bevor Sie etwas ändern, sonst kann es zu Datenverlust kommen!

Struktur des Verzeichnisses

  • data/
    • notes/ Enthält die eigentlichen Notizen, deren Verlauf und Freigaben
      • note_*.history.json Verlauf der Notiz
      • note_*.json Inhalt der Notiz
      • noteslist.json Liste aller IDs der Notizen
      • sharecodes.json Liste aller Freigabecodes
      • shareslist.json Liste der aktuellen Freigaben
    • user/ Enthält Userlisten, Zuordung User zu Notizen
      • user_*.json Zuordung User zu Norizen
      • userslist.json List aller IDs der User
    • config.example.json Beispiel für die Systemkonfiguration
    • config.json Systemkonfiguration, wird vom Installer geschrieben
    • userlist.json Liste aller Useraccounts

(* ist Platzhalt für IDs)

Bestimmte Dateien

Angaben:

  • "änderbar": kann in der JSON angepasst werden, ohne Probleme zu erzeugen
  • "vom User änderbar": kann der User selbstständig über das Frontend ändern
  • "vom User einstellbar": kann vom User bei Erstellung der z.B. Freigabe angepasst, beinflusst werden
  • "nicht änderbar": Änderungen können die Datenstruktur beschädigen

"vom User änderbar/ einstellbar" kann natürlich auch direkt verändert werden, sollte aber der Sicherheit halber über das Frontend geschehen!

Achtung: Sollte eine der Dateien nach den Änderungen kein valides JSON mehr sein, dann wird ihr gesamter Inhalt auf [] zurückgesetzt!

userlist.json - Liste aller Useraccounts:

Array mit Objekt für jeden User. Ein Objekt ist wie folgt aufgebaut:

{
    "username": "String (Username; änderbar)",
    "password": "String (PasswortHash sha256( sha256( <pass> ) '+' <salt> ) ); vom User änderbar )",
    "salt": "String (Salt für PasswortHash; vom User änderbar)",
    "userid": "String (eindeutige UserID; nicht änderbar)",
    "admin": Boolean (Adminrechte; änderbar),
    "authcodes": {
        "String (Authcode)": Integer (UNIX-Timestamp zuletzt verwendet; vom User einstellbar),
    }
},

sharecodes.json & shareslist.json - Freigaben:

Die sharecodes.json enthält ein einfaches Array aller jemals benutzten Codes für Freigaben, dadruch können Kollisionen verhindert werden.

Die shareslist.json enthält ein Array mit Objekten für jede einzelne Freigabe, ein Objekt besteht aus:

{
    "authcode": "String (Authcode für die Freigabe; änderbar)",
    "noteid": "String (ID der freizugebenden Noriz; vom User einstellbar)",
    "edit": Boolean (Bearbeiten erlauben; vom User einstellbar),
    "lastAccessed": [ Integer (Zeitpunkt eines Aufrufs; änderbar)
        ],
    "created": Integer (Zeitpunkt der Erstellung; änderbar),
    "name": "String (Name der Freigabe; vom User einstellbar)"
},

user_*.json & userslist.json - User zu Notiz Zuordung:

Die userslist.json enthält ein einfaches Array aller jemals genutzten UserIDs, somit können Kollisionen verhindert werden.

Für jeden User gibt es eine user_*.json, wobei das * für seine UserID steht. In der Datei befindet sich eine Array mit Objekten für jede Notiz, die dieser User in seiner Notizliste hat.

{
    "name": "String (Name der Notiz in der Notizliste; änderbar)",
    "noteid": "String (ID der Notiz; nicht änderbar)",
    "position": Integer (Sortierung in der Notizliste, größer weiter oben; änderbar),
    "starred": Boolean (Notiz hervorheben, optional)
},

note_*.history.json & note_*.json - Inhalt der Notiz:

Die note_*.json, wobei das * für die ID der Notiz steht, enthält ein einfaches Objekt mit den Werten der Notiz.

{
    "noteid": "String (ID der Notiz; nicht änderbar)",
    "userid": "String (UserID des Eigentümers; änderbar, Notiz einem anderen übertragen)",
    "name": "String (Name der Notiz; änderbar, vom User einstellbar)",
    "content": "String (Inhalt der Notiz; vom User änderbar)",
    "geandert": Integer (Unix-Timestamp der letzten Änderung; vom User einstellbar),
    "erstellt": Integer (Unix-Timestamp der Erstellung der Notiz; vom User einstellbar)
}

Die note_*.history.json, wobei das * für die ID der Notiz steht, enthält ein einfaches Array mit den verschiedenen Versionen der Notiz. Wobei auch jeweils der Zeitpunkt der Version gespeichert ist.