documentation

README.md

@@ -1,3 +1,277 @@
-# drs
+## dierundestunde
+Hugo-Projekt mit Bilder von _Die Runde Stunde_. 
 
-Die Runde Stunde
+Das Hugo-Projekt liegt auf github. Die erstellen Blog-Beiträge liegen im separaten gitea-Bereich [dierundestunde](https://kollegen.uber.space/gitea/dierundestunde/). Der Bild-Content wird dageben nicht versioniert, sondern immer generiert. 
+
+Es muss folgende Verzeichnisstruktur vorliegen:
+```bash
+    ~/
+      .ssh/                      # SSH-Konfiguration
+      dierundestundegen/ 
+        dierundestunde/          # GitHub-Projekt
+          redaktion/        
+            generate_content.py  # Hugo-Content neu erzeugen
+        dropin/                  # neue Bilder hier hinein legen
+        images/                  # verabeitete Bilder, nicht manuell ändern
+        generate.sh              # Zum Neuaufbau des Web-Contents
+      drs-posts/                 # Gitea-Projekt
+        data                     # Beiträge
+      html/                      # User-Web-Content
+        /dierundestunde          # Wird von generate.py neu aufgebaut
+      usr/bin                    # Hier liegt hugo
+```
+
+### Initiales Setup des lokalen Rechners
+
+Mit dem lokalen Rechner wird zum Einen bei Bedarf das Hugo-Projekt angepasst. Für den Upload der Bilder muss aber auf jeden Fall das Upload-Skript vorhanden sein und alle Vorraussetzungen dafür erfüllen. 
+
+#### Setup um Hugo-Projekt pflegen
+
+Um am Projekt etwas ändern zu k̨önnen, sind die git-Repositories am besten in die oben beschriebenen Verzeichnisstruktur wie clonen. Lokal kann die extended Version von Hugo genutzt werden, falls am Template bzw. Styling etwas geändert wird. Wo hugo extended installiert wird is frei wählbar, z.B. in dierundestundegen/hugo. Soll allerdings hugo wie auf Uberspace ausgeführt werden (nicht die extended Version), ist hugo nach ~/usr/bin zu installieren, damit das generation-Skript hugo findet und keine Anpassen vorgenommen werden müssen.
+
+#### Setup um Bilder hochladen zu k̨önnen
+Um neue Bilder der Hugo website hinzuzufügen wird am einfachsten das Bash-Skript upload.sh verwendet. Weiter unten ist aber auch der manuelle Weg beschrieben. Jedenfalls muss das JPG verkleinert und anschlißend nach dropin hochgelanden werden und zu guter letzt das generate-Skript auf dem Host ausgeführt werden, welches dann Hugo neu generiert und in das web-Verzeichnis kopiert.
+
+##### Der einfache Weg: Upload-Script
+
+Sind alle Voraussetzungen für das Script erfüllt (s. nächstes Kapitel), ist das hinzufügen neuer Bilder aus einem Quellverzeichnis simpel:
+
+```bash
+    # <pfad/zum/script/upload.sh> <pfad/zu/den/original/bildern>
+    local$ ~/dierundestundegen/dierundestunde/redaktion/uplod.sh ~/photo/f/02_Progress/drs/20220119/final/
+```
+
+##### Setup bzw. der manuelle Weg
+
+Auf dem Rechner als prüfen und ggf. installieren:
+ * rsync
+ * convert
+ * sshpass
+ * ssh incl. ssh-agent
+
+Der Command __rsync__ ist in der Regel bereits installiert. 
+
+Der Command __convert__ ist Teil von imagemagick:
+
+```bash
+    local$ sudo apt install imagemagick
+```
+
+__SSH__  
+Wird für Zugriff auf uberspace als auch auf gitHub verwendet. Dazu muss ein Schlüsselpaar generiert und in ~/.ssh abgelegt sein. Die dabei zu definierende Passphrase (das Passwort), ist in keepass sicher abzulegen. Der so erzeugte SSH-Schlüssel wird für alle Zugänge verwendet.
+
+```bash
+    ~/  
+      .ssh/                       
+       id_ed25519                # Einzige Ablage des privater Schlüssel  
+       id_ed25519.pub            # Kopiervorlage für uberspace und GitHub  
+       config                    # Konfiguration für ssh-Forwarding  
+```
+
+Wie in den beiden Dokumentationen (uberspace-Manual [SSH](https://manual.uberspace.de/basics-ssh/) bzw.  github-Dokumentation [Connecting to GitHub via SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)) beschrieben, ist der Public Key auf uberspace und auf GutHub abzulegen. 
+
+Wichtig ist, dass der __ssh-agent__ funktioniert und die Passphrase speichert. 
+
+```unformatted
+    local$ ssh-add ~/.ssh/id_ed25519  
+    Enter passphrase for /home/chris/.ssh/id_ed25519:   
+    Identity added: /home/chris/.ssh/id_ed25519 (chris@debian-egh)  
+```
+
+Das generate-Script, welches per SSH auf uberspace ausgeführt wird, benötigt das für den GitHub-Zugriff. Dazu muss in der Config-Datei folgender Eintrag stehen:
+
+> __*~/.ssh/config*__  
+>  
+> ForwardAgent yes  
+
+So eingerichtet, kann der Zugriff auf GitHub von uberspace heraus erfolgen. Test:
+
+```unformatted
+    local$ ssh kollegen@despina.uberspace.de "cd ~/tmp && rm -f -r dierundestunde && git clone git@github.com:chs8691/dierundestunde.git"  
+    Cloning into 'dierundestunde'...
+```
+
+### Initiales Setup von Uberspace
+Per ssh einloggen 
+
+```unformatted
+    local$ ssh kollegen@despina.uberspace.de
+``` 
+
+Hugo in der neuesten Version installieren, wie im [User Lab](https://lab.uberspace.de/guide_hugo.html) beschrieben. Ggf. bereits installierte Version in ~/bin vorher löschen. Hugo-Installation prüfen:
+
+```unformatted
+    host$ ~/bin/hugo version
+    host$ hugo v0.90.1...
+```
+
+> __*Hinweis*__ 
+>
+> Auf Uberspace wird kein Hugo extended verwendet, da einige Library-Versionen nicht passen. Deshalb ist eine > Präprozessierung von SASS nach CSS nicht möglich. Als Workaround werden die CSS-Dateien lokal einmalig mit Hugo extended erzeugt und dann auf das Layout auf CSS umgestellt (in head.html, s.u.).  
+
+Verzeichnisse anlegen:
+
+```unformatted
+    host$ mkdir ~/dierundestundegen
+    host$ cd ~/dierundenstundegen
+    host$ mkdir dropin
+    host$ mkdir images
+```
+
+Git-Repositories holen:
+
+```unformatted
+    host$ git clone https://kollegen.uber.space/gitea/dierundestunde/drs-posts.git 
+    host$ git clone https://github.com/chs8691/dierundestunde.git   
+    host$ cd dierundestunde
+```
+
+Venv für Python 3 anlegen. Dafür sorgen, dass pip auf dem neusten Stand ist. Besonderheit auf dem Server:
+pip immer mit --user ausführen!
+    
+```unformatted
+    host$ cd ~/dierundestundegen/dierundestunde/redaktion
+    host$ python3.9 -m venv venv 
+    host$ venv/bin/python -m pip install --upgrade --no-cache-dir pip
+    host$ venv/bin/python -m pip install -r resources.txt
+```
+
+Da noch keine Bilder vorhanden sind, wird eine erste Generierung nur eine Info ausgeben:
+
+```unformatted
+    host$ venv/bin/python generate_content.py
+    host$ No images found. --- Good bye ---
+```
+
+Skript für Web-Generierung ins Hauptverzeichnis kopieren (muss wiederholt werden, wenn das Script geändert wurde):
+
+```unformatted
+    host$ cp ~/dierundestundegen/dierundestunde/redaktion/generate.py ~/dierundestundegen/
+```
+
+Das Skript pulled die git-Repros und startet die hugo-Generierung. Anschließend wird die Hugo-Site nach ~/html kopiert.
+
+Damit ist das (leere) Hugo-Projekt einsatzbereit.
+
+### Bilder-Content manuell erzeugen bzw. updaten
+
+Ein Bild muss folgende Kriterien entsprechen:
+* JPG-Format
+* Geo-Koordinaten getaggt
+* Optional: Title getaggt 
+
+Original Bild verkleinern, z.B.:
+
+```unformatted
+    local$ convert ~/mypicture/IMG001.JPG -resize 1900x ~/tmp/IMG001.JPG
+```
+
+Nun noch das neue Bild in _dropin_ ablegen und anschließend den Hugo Content generieren.
+
+```unformatted
+    local$ rsync ~/tmp/IMG001.JPG kollegen@uberspace.de:/home/kollegen/dierundestundegen/dropin
+```
+
+Hugo Content daraus generieren und in Webspace befördern. Dazu muss nur das Script auf dem Host ausgeführt werden:
+
+```unformatted
+    local$ ssh kollegen@despina.uberspace.de 'cd dierundestundegen/dierundestunde/redaktion; venv/bin/python ~/dierundestundegen/dierundestunde/redaktion/generate_content.py && ~/dierundestundegen/dierundestunde/redaktion/generate.sh' 
+    local$ ...
+    local$ Congratulations! Generation done.
+```
+
+### CSS erzeugen
+
+Das Theme 'Hugo Story' wurde leicht angepasst und ist deshalb Bestandteil des Repositories (also kein git submodule). Da auf Uberspace Hugo extendend nicht verwendet werden kann, wurde, anstatt präprozessiertem sass, css direkt verwendet. Soll das Theme 'Hugo Stories' aktualisiert werden (lokaler Rechner, hier nicht beschrieben), ist sind folgende Dateien vorher zu sichern und nach dem Update manuell einzuarbeiten:
+
+```unformatted
+    themes/hugo-story/layouts/partials/head.html        <-- geändert
+    themes/hugo-story/layouts/partials/head_css.html    <-- ergänzt
+    themes/hugo-story/layouts/partials/head_sass.html   <-- ergänzt
+```
+
+Auf dem lokalen Rechner ist dann einmalig die SASS-Konvertierung durchzuführen. Dazu in head.htlm ändern:
+
+*themes/hugo-story/layouts/partials/head.html*
+```unformatted
+> \<!-- {x{ partial "template/head_css" . }x}  --> <br>
+> {{ partial "template/head_sass" . }}
+```
+
+> __*Hinweis*__ 
+>
+> In der kommentierten Zeile keine Doppelklammern verwenden, da Hugo auch Kommentare parst.  
+
+Dann mit dem aktuellen Release von hugo extended den SASS-Präprozessor durchführen:
+
+```unformatted
+    local$ cd ~/dierundestundegen/dierundestunde 
+    local$ ~/hugo-extended/hugo 
+    local$ rm ~/dierundestundegen/dierundestunde/themes/hugo-story/assets/css/*.css    
+    local$ cp ~/dierundestundegen/dierundestunde/public/assets/css/*.css ~/dierundestundegen/dierundestunde/themes/hugo-story/assets/css/
+```
+
+Nun wieder auf die Verwendung der css-Dateien switchen.
+
+*themes/hugo-story/layouts/partials/head.html*
+```unformatted
+> {{ partial "template/head_css" . }}
+> \<!-- {x{ partial "template/head_sass" . }x}  -->
+```
+
+### Post posten
+
+Das ist nicht sehr bequem, es werden aber auch nicht sensationell viele Beiträge zu erwarten sein :*)
+
+#### Post erstellen oder bearbeiten (lokal)
+
+Lokal bearbeitet man Posts, indem das Post-Verzeichnis aus dem drs-post nach data kopiert wird, der Post dort  bearbeitet getestet wird. Am Ende den Inhalt zurückkopieren und pushen. Auf dem Server dann Hugo neu generieren und aktiv setzen.
+
+Post erstellen oder bearbeiten:
+```unformatted
+    local$ cd ~/dierundestundegen/dierundestunde
+    local$ mv ../drs-posts/data/post data/
+    local$ vi post/20211210.yml     # Post erstellen   
+```
+
+Nach dem lokalen Test mit hugo server, pushen:
+
+```unformatted
+    local$ mv data/post/ ../drs-posts/data/
+    local$ git add . && git commit -m 'new post'
+    local$ git push   
+```
+
+Jetzt generieren und aktivieren:
+
+```unformatted
+    local$ ssh kollegen@despina.uberspace.de '~/dierundestundegen/dierundestunde/redaktion/generate.sh' 
+```
+
+Generate funktioniert nur, wenn die Repos auf dem Server keine lokalen Änderungen haben.
+
+
+#### Kleine Korrekturen (Server)
+
+Das gleiche Prozedere, nur auf dem Server und ohne Test.
+
+Post erstellen oder bearbeiten:
+```unformatted
+    host$ cd ~/dierundestundegen/dierundestunde
+    host$ mv ../drs-posts/data/post data/
+    host$ vi post/20211210.yml     # Post erstellen   
+```
+
+Nach dem lokalen Test mit hugo server, pushen:
+
+```unformatted
+    host$ mv data/post/ ../drs-posts/data/
+    host$ git add . && git commit -m 'new post'
+    host$ git push   
+```
+
+Jetzt generieren und aktivieren:
+
+```unformatted
+    host$ ~/dierundestundegen/dierundestunde/redaktion/generate.sh
+```