Modernes Dokuwiki für Infrastrukturdokumentation

Am 2015-09-25 hielt ich (bongo) einen Vortrag über mein den Weg zu einer Dokumentationslösung, meine Anforderungen, wovon mir abgeraten wurde und woran ich letzendlich hängen blieb.

• Mir wurde abgeraten von Confluence (Atlassian)
• Wikitten kann keine Volltextsuche
• MDwiki hat keinen Index
• Nachbauen einer eigenen Lösung mit eigener Searchengine… neee

1. Hell/freundlich ⇒ Github, Duckduckgo, Soundcloud, Twitter sind das was ich gerne benutze ⇒ Maßstab
2. Gute, große Buttons
3. Viele intuitive, hochauflösende Icons
4. HTML5
5. Abgerundete Ecken
6. Volltextsuche
7. Vollständiger Index-Baum (links)
8. Markdown-Syntax

(Ich gehe davon aus ihr könnt mit git rudimentär umgehen, eine Shell bedienen und Apache konfigurieren)

• Apache Webserver (ich verwende noch 2.2x)
  • mod_cgi aktiviert
• Dokuwiki bereits installiert
  • Plugins
    • gitbacked (zeigt immer ein verfügbares Update an obwohl es keines gibt)
    • indexmenu (für den indexbaum an der Seite)
    • markdowku (für markdown)
  • Templates (so heißen die Themes)
    • Bootstrap 3 von Giuseppe Di Terlizzi
• Git
• Eine Webhook-Kompatible Git-Verwaltung (z.B. gitlab, github; siehe https://chaos.expert)

• dokuwiki installieren
• wiki konfigurieren
  • bootstrap3 als design template auswählen
  • Gitbacked
    • pushAfterCommit ⇒ JA
    • periodicPull ⇒ NEIN
    • repoPath ⇒ ./data/pages
    • repoWorkDir ⇒ ./data/pages
  • Sidebar
    • left
• Erstellen der Seite „sidebar“ mit Inhalt:

  {{indexmenu>:|js#bj-tango.png navbar id#random skipfile+/(sidebar|hooks)/}}

• Erstellen von ./data/pages/hooks/web_hook.cgi

    #!/usr/bin/env bash
    echo -ne 'Content-type: text/plain\r\n\r\n'

    # ''Updating''
    cd $DOCUMENT_ROOT/data/pages/
    git pull 2>&1

    # From https://www.dokuwiki.org/caching "All of DokuWiki's cache files can be easily invalidated by “touching” the conf/local.php file"
    touch $DOCUMENT_ROOT/conf/local.php
    echo $?
    echo .

• Erstellen der Datei ./data/pages/hooks/.htaccess

    AuthUserFile /var/www/wiki/data/pages/hooks/.htpasswd
    AuthType Basic
    AuthName "hooks"

    # Here is where we allow/deny
    Order Deny,Allow
    Satisfy any
    Deny from all
    Require valid-user

• Erstellen der ./.htaccess Datei für das ganze Wiki (BasicAuth-Teil nur für private Wikis, oder der dokuwiki auth nicht traut)

  
    RewriteEngine On
    
    RewriteCond %{THE_REQUEST} !^GET\ /.*?static/(css|js|img)
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php [L,QSA]
    
    # set an environment variable "noauth"
    SetEnvIf Request_URI ^/web_hook\.cgi noauth=1
    
    AuthUserFile /var/www/wiki/.htpasswd
    AuthType Basic
    AuthName "."
    
    # Here is where we allow/deny
    Order Deny,Allow
    Satisfy any
    Deny from all
    Require valid-user
    Allow from env=noauth

• Konfigurieren des Apache-Vhosts

<IfModule mod_ssl.c>
<VirtualHost *:443>
        ServerAdmin webmaster@localhost
        ServerName wiki.myomain.example

        DocumentRoot /var/www/wiki
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /var/www/wiki>
                Options -Indexes +FollowSymLinks +MultiViews
                AllowOverride All
                Order allow,deny
                allow from all
        </Directory>

        <DirectoryMatch ".*/\.(git|svn|ssh)/.*">
                Require all denied
        </DirectoryMatch>

        <LocationMatch "/(data|conf|bin|inc)/">
            Order allow,deny
            Deny from all
            Satisfy All
        </LocationMatch>

        ScriptAlias /web_hook.cgi /var/www/wiki/data/pages/hooks/web_hook.cgi

        ErrorLog ${APACHE_LOG_DIR}/error.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/ssl_access.log combined

        #   SSL Engine Switch:
        #   Enable/Disable SSL for this virtual host.
        SSLEngine on

        SSLCertificateFile    /etc/ssl/certs/myhost.crt
        SSLCertificateKeyFile /etc/ssl/private/myhost.key
        SSLCertificateChainFile /etc/ssl/certs/wosign_root_bundle.crt


        # Im Zweifel mal bei https://cipherli.st oder https://bettercrypto.org schauen
        SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
        SSLProtocol All -SSLv2 -SSLv3
        SSLHonorCipherOrder On

</VirtualHost>
</IfModule>

• Sicherstellen dass 'git pull' in ./data/pages funktioniert
• .htpasswd Files erstellen

• https://webhooks:SUPERSECRET@wiki.mydomain.example/web_hook.cgi

  als Webhook in Gitlab (o.ä.) registrieren

• Falls man keine Webhooks verwenden will, kann man das web_hook script auch lokal einbinden. Siehe .git/hooks/ Verzeichnis. (Danke joshi)
• Statt .htaccess zu verwenden sollte man die Regeln in die apache-config schreiben und somit ein umgehen der webhook-auth über das Git-Repo zu verhindern (schlimmstenfalls DoS). (Verhindert aber auch eventuelles „Backupen“ des gesamten Dokuwiki-roots über git ;)) (via schiermi)
• Effektiv haben wir durch das Git eine zweite Versionsverwaltung, denn dokuwiki führt selbst eine Seitenhistorie. (via SchMA)
  • ⇒ Änderungen die über git gemacht werden sind nicht in der dokuwiki-Seitenhistorie zu sehen!
  • es wäre denkbar, die Trigger von gitbacked zu erweitern