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

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

```bash
    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.

```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 der Uberspace-Dokumentationen (uberspace-Manual [SSH](https://manual.uberspace.de/basics-ssh/)) beschrieben, ist der Public Key auf uberspace abzulegen. 

Wichtig ist, dass lokal der __ssh-agent__ funktioniert und die Passphrase speichert. 

```unformatted
    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 

```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/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!
    
```unformatted
    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:

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

```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/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:

```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/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*
```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)

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:
```unformatted
    local$ cd ~/dierundestundegen/drs
    local$ vi data/post/20211210.yml     # Post erstellen   
```

Nach dem lokalen Test mit hugo server, pushen:

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

Jetzt generieren und aktivieren:

```unformatted
    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:
```unformatted
    host$ cd ~/dierundestundegen/drs
    host$ vi data/post/20211210.yml     # Post erstellen   
```

Nach dem lokalen Test mit hugo server, pushen:

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

Jetzt generieren und aktivieren:

```unformatted
    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:

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