====== Pelican ======
[[http://blog.getpelican.com/|Pelican]] ist ein in Python geschriebener Static Site Generator, mit dem man auf Basis von Markdown einen Blog mit statischen HTML-Seiten erstellen kann.

===== Vorbereitung =====

Für die Installation müssen erst, sofern nicht vorhanden, die benötigten Pakete installiert werden:
  $ sudo pacman -S python python-pip python-virtualenv
Der Einfachheit halber lege ich einen separaten User ''pelican'' an, über den das Blog (später automatisch) verwaltet wird. Dabei ''http'' entsprechend an die Gruppe anpassen, der der Webserver angehört
  $ sudo useradd -m -g http -s /bin/bash pelican
Dem User ein Passwort zuweisen
  $ sudo passwd pelican
Der Gruppe (somit auch dem Webserver) Zugriff auf das User-Verzeichnis einräumen
  $ sudo chmod 750 /home/pelican

==== nginx ====

''nginx'' für Pelican vorbereiten
<code - /etc/nginx/ngnix.conf>
    server {
        listen 443 ssl;
        server_name blog.domain.tld;
        root /home/pelican/blog/output;
        index index.html;

        error_log /var/log/nginx/pelican-error.log warn;

        ssl_certificate /etc/nginx/ssl/domain.tld.pem;
        ssl_certificate_key /etc/ssl/private/domain.tld.key;

        location ~ ^/feeds {
            autoindex on;
        }
    }
</code>

===== Einrichtung =====

Haben wir alle Vorbereitungen getroffen, geht es an die eigentliche Einrichtung. Dazu zum ''pelican''-Nutzer wechseln
  $ su pelican
Nun in das Home-Verzeichnis wechseln, um dort die Einrichtung vorzunehmen
  $ cd /home/pelican
Jetzt müssen die Ordner für die eigentlichen Daten erstellt werden. Für die virtuelle Umgebung verwende ich ''blogenv'', die Daten für den Blog-Inhalt selbst landen im Ordner ''blog''
  $ mkdir blog blogenv
Ein virtual environment für Python anlegen, worin Pelican und Abhängigkeiten installiert werden
  $ virtualenv blogenv
Dieses virtual environment aktivieren und Pakete installieren
  $ source blogenv/bin/activate
  $ pip install pelican Markdown typogrify
Als nächstes muss die Blog-Umgebung eingerichtet werden. Dabei die Fragen so gut es geht beantworten. Sie können später noch über die erstellte Konfigurationsdatei ''pelicanconf.py'' im ''blog''-Ordner verändert werden.
  $ pelican-quickstart -p blog

Wechseln in den ''blog''-Ordner
  $ cd blog
Typogrify zur ''pelicanconf.py'' hinzufügen:
<code python>
TYPOGRIFY = True
</code>
Markdown Einträge im Ordner ''content'' erstellen, zum Erzeugen der fertigen Website-Struktur im ''blog''-Ordner
  $ make publish
aufrufen.

Da ''pelican'' generell nur für den Blog verwendet wird, das ''virtualenv'' zur ''.bashrc'' hinzufügen:
<code bash>
source ~/blogenv/bin/activate
</code>
So befindet man sich nach dem Einloggen als ''pelican'' direkt in der virtuellen Python-Umgebung.

===== Modifizierungen & Erweiterungen =====

Plugins hinzufügen, dazu das entsprechende GitHub Repository clonen
  $ git clone https://github.com/getpelican/pelican-plugins.git plugins
Die jeweiligen Plugins in der ''pelicanconf.py'' eintragen, hier beispielhaft an drei Plugins dargestellt
<code python>
PLUGIN_PATHS = ['plugins']
PLUGINS = ['feed_summary', 'gzip_cache', 'render_math']
</code>
Themes können genauso in z. B. den Ordner ''themes'' geklont werden, aktiviert wird es wieder in der ''pelicanconf.py''
<code python>
THEME = 'themes/cloned-repo-name'
</code>

Zusätzliche Seiten wie Archiv, die Link-Struktur und mehr können ebenfalls über die ''pelicanconf.py'' eingestellt werden:
<code python ~/blog/pelicanconf.py>
# Formatting for dates
DEFAULT_DATE_FORMAT = ('%A, %d %B %Y')

# Formatting for urls

ARTICLE_URL = "{date:%Y}/{date:%m}/{slug}/"
ARTICLE_SAVE_AS = "{date:%Y}/{date:%m}/{slug}/index.html"

CATEGORY_URL = "category/{slug}"
CATEGORY_SAVE_AS = "category/{slug}/index.html"

TAG_URL = "tag/{slug}/"
TAG_SAVE_AS = "tag/{slug}/index.html"

# Generate yearly archive

YEAR_ARCHIVE_SAVE_AS = '{date:%Y}/index.html'
MONTH_ARCHIVE_SAVE_AS = '{date:%Y}/{date:%b}/index.html'
</code>

===== Upgrade der virtuellen Umgebung =====

Die angelegte virtuelle Umgebung unter ''blogenv'' muss unter Umständen aktualisiert werden, beispielsweise nach einem Upgrade von Python selbst auf dem Server. Dies kann dazu führen, dass beim Versuch, die Beiträge mit einem ''make publish'' zu erstellen, eine Fehlermeldung wie
  blogenv/bin/python3: error while loading shared libraries: libpython3.5m.so.1.0: cannot open shared object file: No such file or directory
erscheint. Grund ist hier das Upgrade von Python 3.5 auf 3.6.

Bevor wir die mit ''virtualenv'' angelegte Umgebung aktualisieren, erstellen wir besser ein Backup der Daten; im Folgenden gehe ich davon aus, dass wir uns, sofern nicht anders angegeben, im Verzeichnis ''/home/pelican'' befinden:
  $ cp -r blogenv blogenv_backup

Danach muss die Python-Version mittels Downgrade auf die letzte funktionierende Version gesetzt werden, damit wir der Einfachheit halber alle installierten Module ermitteln, um sie nachher einfach wieder zu installieren. Am besten wurde der Cache der ''pacman''-Pakete nicht geleert, so kann in ''/var/cache/pacman/pkg'' nach den vorhandenen alten Python-Paketen gesucht werden, in meinem Fall die Version 3.5.2. Diese installieren wir:
  # pacman -U /var/cache/pacman/pkg/python-3.5.2-3-armv7h.pkg.tar.xz

Nun kann die virtuelle Umgebung aktiviert werden, um die verwendeten Module zu ermitteln:
  # source blogenv/bin/activate
  # pip freeze > requirements.txt
  # deactivate
  # rm -rf blogenv
Bei dem letzten Schritt wird die Umgebung gelöscht, weswegen das Backup sinnvoll ist.

Anschließend kann Python wieder aktualisiert werden:
  # pacman -S python

Die neue Umgebung richten wir als Benutzer ''pelican'' ein, weswegen noch schnell die Berechtigungen angepasst werden:
  # chown pelican:http requirements.txt
  # su pelican
An diesem Punkt sicherstellen, dass das Arbeitsverzeichnis ''/home/pelican'' ist.

Die neue Umgebung kann nun eingerichtet werden:
  $ virtualenv blogenv
  $ source blogenv/bin/activate
  $ pip install --upgrade -r requirements.txt

Nach Ausloggen und erneutem Einloggen mit ''su pelican'' sollte nun wieder alles wie vorher sein und auch das Erstellen der Beiträge mittels ''make publish'' sollte ohne Fehlermeldung das gewünschte Resultat liefern. Das Backup ''blogenv_backup'' kann entsprechend gelöscht werden, hat alles funktioniert.

===== Automatisierung mittels git =====

FIXME