Modernes Dokuwiki für Infrastrukturdokumentation

Kurzvortrag

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.

"Was sonstwo benutzt wird"

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

Anforderungen

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

Setup

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

Requirements

  • 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)
  • Eine Webhook-Kompatible Git-Verwaltung (z.B. gitlab, github; siehe https://chaos.expert)

Konfiguration

  • 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>

Anmerkungen aus dem Publikum

  • 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
 
 
projekte/diverses/modern-dokuwiki-git-markdown-bootstrap.txt · Zuletzt geändert: 2015-09-26 02:02 von bongo
Recent changes RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki