User Tools

Site Tools


doc:appunti:linux:sa:dokuwiki

DokuWiki, installazione

Preso il Dokuwiki originale invece del pacchetto Debian, scompattato in /home/dokuwiki/. Per iniziare tutti i file appartengono a root:root, permessi 0644 per i file e 0755 per le directory. Queste le personalizzazioni:

touch data/changes.log
cp conf/users.auth.php.dist conf/users.auth.php
cp conf/acl.auth.php.dist   conf/acl.auth.php
cp conf/local.php.dist      conf/local.php
chgrp www-data conf/users.auth.php
chgrp www-data conf/acl.auth.php
chgrp www-data conf/local.php
chmod 664      conf/users.auth.php
chmod 664      conf/acl.auth.php
chmod 664      conf/local.php
chown -R www-data data

Dare il permesso di scrittura al server web sui file di configurazione users.auth.php, acl.auth.php e local.php serve a permettere l'amministrazione di Dokuwiki da interfaccia web.

Plugin

NOTA: per poter fare il download e l'installazione dei plugin direttamente dall'interfaccia web di amministrazione basta dare i permessi di scrittura su lib/plugins/ al server web. Dopo aver fatto l'installazione si può nuovamente togliere i permessi, anche alla directory del plugin installato.

Effettuata l'installazione dei plugin indexmenu e blog. Il secondo è develonly, cioè funziona solo sulla versione in sviluppo di Dokuwiki. Per l'installazione è stato usato il plugin manager, bisogna fare in modo che il server web possa scrivere la directory lib/plugins. Hanno funzionato correttamente, salvo la necessità di forzare il reload della pagina.

Sidebar (barra laterale)

Per avere una barra laterale, ad esempio per ospitare un indice del sito. In origine disponibile come template, qui il sito web originale e qui la pagina su Dokuwiki.org. Il suo uso tuttavia è sconsigliato perché ad ogni aggiornamento del Dokuwiki bisognerebbe aggiornare lo stile del template per comprendere tutte le novità (nuovi pulsanti, variazioni dello stile predefinito, ecc.).

Molto meglio l'implementazione come plugin che è sostanzialmente indipendente dallo stile/template in uso. Qui la pagina su Dokuwiki.org.

L'installazione e la configurazione si fanno normalmente dall'interfaccia di amministrazione. Provato e funzionante con la versione 2012-01-25 di Dokuwiki.

Patch (modifiche)

Ho modificato alcuni file:

lib/plugins/include/helper.php.dist La funzione blog deve presentare solo la prima parte di un articolo, interrompendo non solo al primo titolo (opzione firstseconly del plugin), ma alla prima occorrenza di una entity (ho scelto )
lib/tpl/sidebar/main.php.dist Nella sidebar compare una scritta hide, che non si capisce bene a cosa serve; tolta!
conf/interwiki.conf Aggiunta la sigla interwiki wpit che punta a Wikipedia Italia.

Qui l'archivio con i file modificati e gli originali (rispetto alla versione 2009-02-14).

Configurazione locale

Queste le configurazioni messe in conf/local.php.

// Configuration of DokuWiki core.
$conf['title'] = 'rigacci.org';
$conf['template'] = 'sidebar';
$conf['breadcrumbs'] = 6;
$conf['useheading'] = 1; //use the first heading in a page as its name
// Temporarly disabled beacause of a problem on PCRE library.
$conf['usewordblock']= 0; // block spam based on words? 0|1
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
$conf['phpok'] = 1;
$conf['compress'] = 0;
$conf['hidepages'] = 'sidebar|blog'; //regexp for pages to be skipped from RSS, Search, Recent Changes and blog
// Make URLs more friendly to webalizer and search engines.
$conf['userewrite'] = 2; //this makes nice URLs: 0: off 1: .htaccess 2: internal
$conf['useslash'] = 1; //use slash instead of colon? only when rewrite is on
 
// Configuration for the Blog plugin.
$conf['plugin']['blog']['showlink'] = 0;
$conf['plugin']['blog']['showdate'] = 0;
$conf['plugin']['blog']['showuser'] = 0;
$conf['plugin']['blog']['sortkey'] = 'pagename';
$conf['plugin']['blog']['stop_on_entity'] = '=>';
 
// Configuration for the Indexmenu plugin.
$conf['plugin']['indexmenu']['headpage']      = 'blog,:start:'; //name for the pages from which retrive the title
$conf['plugin']['indexmenu']['hide_headpage'] = 'true';
$conf['plugin']['indexmenu']['skip_index']    = '/(playground|wiki)$/'; //namespaces to skip
$conf['plugin']['indexmenu']['skip_file']     = ''; //files to skip
$conf['plugin']['indexmenu']['empty_msg']     = 'Sorry, no menu for <b>{{ns}}</b>';

Link relativi

Quando si usano i namespace conviene utilizzare link relativi rispetto alle pagine o ai file. Questa la sintassi da utilizzare:

[[..:..:namespace:page|Two level up page]]
[[.:namespage:page|One level down page]]

URL rewriting and Apache alias

Abbiamo attivato le opzioni $conf['userewrite'] e $conf['useslash'] in modo che gli url generati da DokuWiki siano più adatti ai motori di ricerca e al Webalizer.

URL standard http://www.rigacci.org/wiki/doku.php?id=doc:appunti:linux:sa:dokuwiki
URL rewrite http://www.rigacci.org/wiki/doku.php/doc/appunti/linux/sa/dokuwiki

Inoltre si vuole il DokuWiki nella sottodirectory /wiki/, non a livello della DocumentRoot. I file PHP sono in realtà installati in /home/dokuwiki/, si è provato inizialmente con un alias di Apache:

# WARNING! Does not work with DokuWiki 'userewrite'!
Alias /wiki /home/dokuwiki

Purtroppo in questo modo non funziona. Si è quindi creato un link simbolico dalla DocumentRoot verso /home/dokuwiki, nella configurazione di Apache rimane solo l'indispensabile.

lrwxrwxrwx 1 root root 14 Oct 19 14:37 /var/www/www.rigacci.org/wiki -> /home/dokuwiki/
<Location /wiki/>
    # Disable indexes and enabled symlinks.
    # Without symlinks enabled you may get
    #403 Forbidden errors when url rewriting.
    Options -Indexes +FollowSymLinks
    AllowOverride All
    order allow,deny
    allow from all
</Location>

Forzare https su login

Per forzare il passaggio in https quando si effettua l'autenticazione si aggiunge alla configurazione del VirtualHost:

# Force https for Dokuwiki login.
RewriteEngine On
RewriteCond %{HTTPS} !on
RewriteCond %{QUERY_STRING} \bdo=log(in|out)\b
RewriteRule ^(.*) https://%{HTTP_HOST}/$1 [R,QSA,L]

Cached pages bug on upgrade

After upgrading Dokuwiki Debian package from version 20050713-2 to 0.0.20060309-3, I got several pages with junk messages like this:

<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::toc_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />
<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::tocbranch_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />
<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::tocitem_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />

It seems that XML parsing functions changed, so the old cached pages are not longer valid. To invalidate all the cached pages you can simply touch the file dokuwiki/conf/local.php with a new timestamp.

Forzare il refresh dei dati

DokuWiki mantiene in alcuni file dei metadati relativi alle pagine memorizzate, ad esempio la ricerca per testo libero non avviene direttamente sulle pagine, ma su file indice (data/cache/*.idx) per velocizzare l'operazione di ricerca.

Inoltre quando viene generata una pagina, questa viene salvata anche nella cache di DokuWiki, in modo che possa essere servita successivamente.

Ovviamente nel normale utilizzo di DokuWiki la cache dovrebbe essere sempre coerente con i dati, ma in alcune circostanze potrebbe essere necessario forzare un aggiornamento.

Pagina non da cache

Per forzare la generazione di una pagina senza utilizzare la copia in cache basta chiamare la pagina ed aggiungere all'URL il paramtro &purge=true.

Indici per ricerca

Se una pagina viene aggiunta senza passare per DokuWiki - ad esempio copiando direttamente un file nella directory - l'indice per la ricerca a testo libero non la include. Per rigenerare gli indici .idx si può utilizzare lo script da riga di comando:

cd /home/dokuwiki
php bin/indexer.php
chown -R www-data:www-data ./data

ATTENZIONE! Il comando chown serve a ripristinare le giuste ownership ai file contenuti nella directory data, i file vengono creati con l'owner di chi esegue indexer.php.

Messaggio di notifica

Se è attiva l'opzione $conf['updatecheck'], quando è loggato un amministratore può comparire all'inizio della pagina un messaggio del tipo:

New release available: rc2006-10-08. Fixes a XSS vulnerability - upgrade now! [5]

Teoricamente il messaggio dovrebbe scomparire appena effettuato l'aggiornamento, se dovesse persistere si può rimuovere manualmente il file data/cache/messages.txt. Il messaggio visualizzato dipende dal numero contenuto nella prima riga del file conf/msg: viene fatta una richiesta per messaggi nuovi al server http://update.dokuwiki.org/check/.

Heading (titolo) di pagina

Come fare ad aggiornarlo?

Dokuwiki upgrade

Upgrade from dokuwiki-2008-05-05.tgz to dokuwiki-2009-02-14.tgz. Manual way.

  • Extract the tarball into a new directory and check permissions
  • Merge old data/ directory into the new tree
  • Purge files and directories from data/cache/
  • Merge localized files into conf/ (see below)
  • Restore all locally installed lib/tpl/ and lib/plugins/
  • Regenerate the search indexes (see below)

Configuration files to be restored:

  • acl.auth.php
  • interwiki.local.conf (was interwiki.conf)
  • local.php
  • mime.local.conf
  • plugins.local.php
  • users.auth.php

Example of plugins/templates installed: plugins/include, plugins/indexmenu, plugins/blog, tpl/sidebar.

Fix permissions on all files and directories:

cd dokuwiki_new
chown -R root:root *
find . -type d -print0 | xargs -0 chmod 755
find . -type f -print0 | xargs -0 chmod 644

chgrp www-data conf
chmod 775 conf

chgrp www-data lib/plugins
chmod 775 lib/plugins

for file in local.php acl.auth.php users.auth.php; do
    touch conf/$file
    chgrp www-data conf/$file
    chmod 664 conf/$file
done

touch conf/local.php

Regenerate indexes (to be safe):

php bin/indexer.php
chown -R www-data:www-data ./data

Style customization

In the file lib/tpl/default/style.ini you can read: Changing this file is the simplest method to give your wiki a new look.

One simple way is to make an image with several block filled with the original colors, then adjust the colors as you want (e.g. with GIMP, Adjust Color Balance function). Finally pick the hex value of each color and replace it into the file.

The following PHP script can be used to print a table with all the used colors:

<?php
$fp = fopen('lib/tpl/default/style.ini', 'r');
echo "<table cellpadding=\"3\" cellspacing=\"1\" border=\"1\">\n";
while(!feof($fp)) {
    $line = fgets($fp, 2048);
    if (preg_match('/(\S+)\s*=\s*"#([0-9a-fA-F]+)"/', $line, $matches)) {
        echo '<tr><td>' . $matches[1] . '</td>';
        echo '<td>' . $matches[2] . '</td>';
        echo '<td width="180" bgcolor="' . $matches[2] . "\">&nbsp;</td></tr>\n";
    }
}
echo "</table>\n";
fclose($fp)
?>

Plugins customization

Here it is some patches to indexmenu (2009-08-29) and include (2009-11-27) plugins, they are working with Dokuwiki 2010-11-07.

indexmenu: disable context menu from JavaScritp index

Changed the following files:

  • lib/plugins/indexmenu/jsmenu/admmenu.js.dist
  • lib/plugins/indexmenu/jsmenu/menu.js.dist
  • lib/plugins/indexmenu/jsmenu/usrmenu.js.dist

commented out the var indexmenu_contextmenu declaration.

include plugin: limit included text untill special char

Changed the following file:

  • lib/plugins/include/helper.php

added a statement which searches for the entity and treats it like the end of the first section.

Plugin dw2pdf (esporta PDF)

Il plugin dw2pdf aggiunge la funzione “esporta PDF” ad ogni pagina.

  • Si installa come gli altri plugin.
  • Il PDF si ottiene aggiungendo all'URL il parametro do=export_pdf.
  • Per aggiungere un pulsante Esporta PDF si deve modificare il template in uso. Ad esempio in lib/tpl/default/main.php si aggiunge nel div id="bar__bottomleft" il seguente codice:
    <form class="button" method="get" action="<?php wl($ID)?>">
      <div class="no">       
        <input type="submit" value="Export to PDF" class="button" />
        <input type="hidden" name="do" value="export_pdf" />
        <input type="hidden" name="id" value="<?php echo $ID?>" />
      </div>            
    </form>

Personalizzazione

Alcuni aspetti del PDF generato (ad esempio le intestazioni e i piè di pagina) possono essere personalizzati configurando il plugin.

Lo stile per la creazione del PDF è controllato dagli stili contenuti in dw2pdf/tpl/default/, è possibile creare altre directory e poi scegliere quale stile usare da AmministrazioneConfigurazione Wiki.

FIXME Valido per la vecchia versione del plugin: i selettori devono fare riferimento alle classi della pagina web, escludendo il parent div.dokuwiki.

Intestazioni e piè di pagina

FIXME Problema riscontrato con la vecchia versione del plugin: Sembra che ci sia un bug per cui non viene usata l'intestazione e piè di pagina per le pagine dispari (odd), ma viene usata quella delle pagine pari, scambiando il lato destro con il sinistro. Forse è un bug della libreria mPDF?

Se si vuole evitare l'effetto mirror si imposta $mpdf->mirrorMargins = 0 in action.php, in questo modo verranno usati intestazione e piè di pagina delle pagine pari (even), senza l'effetto mirror.

Bug PDF corrotto

C'era un bug nella versione dw2pdf del 2012-05-20, per cui il PDF generato è corrotto alla prima richiesta, ma è buono dalla seconda in poi. Il tutto è causato da un errore il cui output si inserisce nel file PDF generato, mentre nelle richieste successive il file viene recuparato dalla cache e quindi è valido.

Il bug è stato risolto il 18 dicembre 2013, con il commit 28e636e.

No input file specified

In alcune installazioni, quando si attiva l'opzione userewrite si può incappare nell'errore:

No input file specified.

La soluzione può essere quella di impostare il paramtero PHP cgi.fix_pathinfo (che dovrebbe essere abilitato come impostazione predefinita):

cgi.fix_pathinfo = 1

Per attivare l'opzione userewrite = 2 bisogna che il server gestisca il PATH_INFO, per verificare si può creare una pagina pathinfo.php con questo codice:

<?php print "PATH_INFO = " . $_SERVER['PATH_INFO']; ?>

puntando il browser all'indirizzo http://example.server.org/pathinfo.php/PROVA123 si deve ottenere la risposta:

PATH_INFO = /PROVA123

Riferimenti web

doc/appunti/linux/sa/dokuwiki.txt · Last modified: 2015/11/05 10:02 by niccolo