dierundestunde

Hugo-Projekt mit Bilder von Die Runde Stunde.

Das Hugo-Projekt liegt auf github. Die erstellen Blog-Beiträge liegen im separaten gitea-Bereich dierundestunde. Der Bild-Content wird dageben nicht versioniert, sondern immer generiert.

Es muss folgende Verzeichnisstruktur vorliegen:

    ~/
      .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:

    # <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:

    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.

    ~/  
      .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 bzw. github-Dokumentation Connecting to GitHub via SSH) beschrieben, ist der Public Key auf uberspace und auf GutHub abzulegen.

Wichtig ist, dass der ssh-agent funktioniert und die Passphrase speichert.

    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:

    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

    local$ ssh kollegen@despina.uberspace.de

Hugo in der neuesten Version installieren, wie im User Lab beschrieben. Ggf. bereits installierte Version in ~/bin vorher löschen. Hugo-Installation prüfen:

    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:

    host$ mkdir ~/dierundestundegen
    host$ cd ~/dierundenstundegen
    host$ mkdir dropin
    host$ mkdir images

Git-Repositories holen:

    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!

    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:

    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):

    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.:

    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.

    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:

    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:

    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

> \<!-- {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:

    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

> {{ 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:

    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:

    local$ mv data/post/ ../drs-posts/data/
    local$ git add . && git commit -m 'new post'
    local$ git push   

Jetzt generieren und aktivieren:

    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:

    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:

    host$ mv data/post/ ../drs-posts/data/
    host$ git add . && git commit -m 'new post'
    host$ git push   

Jetzt generieren und aktivieren:

    host$ ~/dierundestundegen/dierundestunde/redaktion/generate.sh