dierundestunde

Hugo-Projekt mit Bilder von Die Runde Stunde.

Das Projekt liegt komplett hier auf gitea. Der Bild-Content wird dageben nicht versioniert, sondern immer generiert.

Es muss folgende Verzeichnisstruktur vorliegen:

    ~/
      .ssh/                      # SSH-Konfiguration
      dierundestundegen/ 
        drs/                     # Gitea-Projekt
            data                 # Blog-Beiträge
            ...                  # Hugo-Website
          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
        hugo-extended/hugo       # Die extended Version (für css-Anpassungen) 
      html/                      # User-Web-Content
        /dierundestunde          # Wird von generate.py neu aufgebaut
      usr/bin                    # Hier liegt hugo in der gleichen Version, wie auf dem Server

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, ist das git-Repository in die oben beschriebenen Verzeichnisstruktur zu clonen. Lokal kann die extended Version von Hugo genutzt werden, falls am Template bzw. Styling etwas geändert wird. Hugo-extended wird unter dierundestundegen/hugo-extended installiert. Um hugo wie auf Uberspace auszuführen (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/drs/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 und auf gitea verwendet. Dazu muss ein Schlüsselpaar generiert und in /home/mylocaluser/.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 der Uberspace-Dokumentationen (uberspace-Manual SSH) beschrieben, ist der Public Key auf uberspace abzulegen.

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

    local$ ssh-add /home/localuser/.ssh/id_ed25519  
    Enter passphrase for /home/localuser/.ssh/id_ed25519:   
    Identity added: /home/localuser/.ssh/id_ed25519 (localuser@localhost)  

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/drs/drs-posts.git 
    host$ cd drs

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/drs/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/drs/redaktion/generate.py ~/dierundestundegen/

Das Skript pulled das git-Repro 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/drs/redaktion; venv/bin/python ~/dierundestundegen/drs/redaktion/generate_content.py && ~/dierundestundegen/drs/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/drs 
    local$ ~/hugo-extended/hugo 
    local$ rm ~/dierundestundegen/drs/themes/hugo-story/assets/css/*.css    
    local$ cp ~/dierundestundegen/drs/public/assets/css/*.css ~/dierundestundegen/drs/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)

Posts liegen in unter drs/data/post. Wird dort geändert, ist nach dem pushen auf den Server die Generierung anzuschmeißen. Auf dem Server dann Hugo neu generieren und aktiv setzen.

Post erstellen oder bearbeiten:

    local$ cd ~/dierundestundegen/drs
    local$ vi data/post/20211210.yml     # Post erstellen   

Nach dem lokalen Test mit hugo server, pushen:

    local$ git add . && git commit -m 'new post'
    local$ git push   

Jetzt generieren und aktivieren:

    local$ ssh kollegen@despina.uberspace.de '~/dierundestundegen/drs/redaktion/generate.sh' 

Hinweis

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/drs
    host$ vi data/post/20211210.yml     # Post erstellen   

Nach dem lokalen Test mit hugo server, pushen:

    host$ git add . && git commit -m 'new post'
    host$ git push   

Jetzt generieren und aktivieren:

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

Troubleshooting

Webcontent neu aufbauen
Ausversehen wurde der Webcontent gelöscht (/home/kollegen/html/). Wie kann der Content wieder erstellt werden?

--> Auf dem Server ist das generate-Skript auszuführen:

host$ /home/kollegen/dierundestundegen/drs/redaktion/generate.sh