====== Dokuwiki Install and Upgrade ======

DokuWiki is a simple to use and highly versatile Open Source [[wp>Wiki]] software that doesn't require a database. It is loved by users for its clean and readable syntax. The ease of maintenance, backup and integration makes it an administrator's favorite. Built in access controls and authentication connectors make DokuWiki especially useful in the enterprise context and the large number of plug-ins contributed by its vibrant community allow for a broad range of use cases beyond a traditional wiki. 

===== Directory Structure =====

The Dokuwiki installation is stored in a dedicated directory typically under the /opt directory.
<code>
/opt
 |
 +-- dokuwiki
     |
     +-- current -> dokuwiki-nnnn-nn-nn
     |
     +-- data
     |
     +-- dokuwiki-pppp-pp-pp
     |
     +-- dokuwiki-nnnn-nn-nn
     |
     +-- template     
</code>

===== Installation =====

Before installing dokuwiki, you'll need a [[webserver|web server and the PHP application engine]] to serve the application.

=== Configure The Web Server ===

Once you have a NGINX and PHP installed, you'll need to configure it to serve the application:

<code bash>
cat > /tmp/dokuwiki << EOF
server {
  listen 127.0.0.1:8080;

  root /opt/dokuwiki/current;
  access_log off;
  error_page 404 /lib/tpl/dokuwiki/404.html;

  location /lib/tpl/dokuwiki/404.html {
    internal;
  }

  location / { 
    index doku.php;
    try_files \$uri \$uri/ @dokuwiki;
  }

  location @dokuwiki {
    rewrite ^/_media/(.*) /lib/exe/fetch.php?media=\$1 last;
    rewrite ^/_detail/(.*) /lib/exe/detail.php?media=\$1 last;
    rewrite ^/_export/([^/]+)/(.*) /doku.php?do=export_\$1&id=\$2 last;
    rewrite ^/(.*) /doku.php?id=\$1&\$args last;
  }

  location ^~ /(bin|conf|data|inc/ { deny all; }
  location  ~ /\.ht  { deny all; }

  location ~ \.php\$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php7.0-fpm.sock
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
    fastcgi_param PATH_INFO \$uri;  # necessary for URL rewrite
    fastcgi_index doku.php;
  }
}
EOF

sudo mv /tmp/dokuwiki /etc/nginx/sites-available/

sudo ln -s /etc/nginx/sites-available/dokuwiki /etc/nginx/sites-enabled/dokuwiki

sudo service nginx reload
</code>

=== Install The Software ===

<code bash>
sudo apt-get install php-xml
cd /tmp
wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-nnnn-nn-nn.tgz
tar xzvf dokuwiki-nnnn-nn-nn.tgz
sudo mkdir -p /opt/dokuwiki
sudo mv dokuwiki-nnnn-nn-nn /opt/dokuwiki/
rm /tmp/dokuwiki-nnnn-nn-nn.tgz

sudo ln -s /opt/dokuwiki/dokuwiki-nnnn-nn-nn /opt/dokuwiki/current

sudo mv /opt/dokuwiki/current/data /opt/dokuwiki/data
sudo mv /opt/dokuwiki/current/lib/tpl/dokuwiki /opt/dokuwiki/template

sudo chown -R www-data:www-data /opt/dokuwiki/dokuwiki-nnnn-nn-nn
sudo chmod -R u-w,g-w,o-w /opt/dokuwiki/dokuwiki-nnnn-nn-nn

sudo chown -R www-data:www-data /opt/dokuwiki/data
sudo chmod -R u+rw,g+rw /opt/dokuwiki/data

sudo chown -R www-data:www-data /opt/dokuwiki/template
sudo chmod -R u-w,g-w,o-w /opt/dokuwiki/template
sudo ln -s /opt/dokuwiki/template /opt/dokuwiki/current/lib/tpl/dokuwiki
</code>

After the core software is installed, remove and add the plug-ins using the instruction below.

=== Complete Dokuwiki Configuration Using Dokuwiki's Editor ===

When setting up a wiki server that will use the built-in editing, I run through Dokuwiki's installer. You'll need to give the web server user write access long enough to complete the configuration:
<code bash>
sudo chmod -R u+w /opt/dokuwiki/current/conf
sudo chmod -R u+w /opt/dokuwiki/data
sudo ln -s /opt/dokuwiki/data /opt/dokuwiki/current/data
</code>
Open web browser to install Dokuwiki. ''http://url.domain.tld/install.php'' Complete the intial configuration, then restrict the write access of the web server:
<code bash>
sudo chmod -R u-w /opt/dokuwiki/current/conf
sudo /bin/rm /opt/dokuwiki/current/data
</code>

=== Complete Dokuwiki Configuration Using External Editor ===

When setting up a wiki server that will use a separate system to edit/maintain the pages and then have the resulting text files copied over, I configure the server to have a locked down configuration:
<code bash>
cat > /tmp/acl.auth.php << EOF
# acl.auth.php
# <?php exit()?>
# Don't modify the lines above
*               @ALL          1
*               @user         8
EOF
sudo mv /tmp/acl.auth.php /opt/dokuwiki/current/conf/acl.auth.php

cat > /tmp/users.auth.php << EOF
# users.auth.php
# <?php exit()?>
# Don't modify the lines above
user:!:User:user@localhost:user
EOF
sudo mv /tmp/users.auth.php /opt/dokuwiki/current/conf/users.auth.php

cat > /tmp/local.php << EOF
<?php
\$conf['savedir'] = '/opt/dokuwiki/data';
\$conf['breadcrumbs'] = 0;
\$conf['youarehere'] = 1;
\$conf['sneaky_index'] = 1;
\$conf['useheading'] = '1';
\$conf['disableactions'] = 'backlink,index,recent,revisions,search,register'
                        . ',resendpwd,profile,check,subscribens,unsubscribens'
                        . ',subscribe,unsubscribe,diff,media';
\$conf['userewrite'] = '1';
\$conf['useslash'] = 1;
\$conf['plugin']['blog']['formposition'] = 'none';
\$conf['plugin']['include']['showeditbtn'] = 0;
\$conf['updatecheck'] = 0;
\$conf['send404'] = 1;
\$conf['license'] = '';
\$conf['maxtoclevel'] = 0;
\$conf['maxseclevel'] = 0;
\$conf['superuser'] = '@admin';
\$conf['rss_linkto'] = 'current';
\$conf['sitemap'] = 1;
\$conf['useacl'] = 1;
?>
EOF
sudo mv /tmp/local.php /opt/dokuwiki/current/conf/local.php

sudo touch /opt/dokuwiki/current/conf/plugins.local.php
</code>

===== =====
At this point, you should have a running configured Dokuwiki site ready for content to be added.

===== Upgrading =====

These are the steps I used to upgrade the installation in case I decide to do it again...

''pppp-pp-pp -> previous \\ 
nnnn-nn-nn -> next''

=== Install The Software ===

<code bash>
cd /tmp
wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-nnnn-nn-nn.tgz
tar xzvf dokuwiki-nnnn-nn-nn.tgz
sudo mv dokuwiki-nnnn-nn-nn /opt/dokuwiki/
rm /tmp/dokuwiki-nnnn-nn-nn.tgz

sudo chown -R www-data:www-data /opt/dokuwiki/dokuwiki-nnnn-nn-nn/
sudo chmod -R u-w,g-w,o-w /opt/dokuwiki/dokuwiki-nnnn-nn-nn/
</code>

After the core software is installed, remove and add the plug-ins using the instruction below.

=== Create a link to the "upgrade" version ===

<code bash>
sudo ln -s /opt/dokuwiki/dokuwiki-nnnn-nn-nn /opt/dokuwiki/upgrade
</code>

=== Copy Configuration ===
<code bash>
sudo /bin/rm -R /opt/dokuwiki/upgrade/data
sudo /bin/rm -R /opt/dokuwiki/upgrade/lib/tpl/dokuwiki

sudo ln -s /opt/dokuwiki/template /opt/dokuwiki/upgrade/lib/tpl/dokuwiki

sudo /bin/cp /opt/dokuwiki/current/conf/acl.auth.php /opt/dokuwiki/upgrade/conf/
sudo /bin/cp /opt/dokuwiki/current/conf/users.auth.php /opt/dokuwiki/upgrade/conf/
sudo /bin/cp /opt/dokuwiki/current/conf/local.php /opt/dokuwiki/upgrade/conf/
sudo touch /opt/dokuwiki/upgrade/conf/plugins.local.php
</code>

=== Move the "current" link to the new installation ===
<code bash>
sudo /bin/rm /opt/dokuwiki/current
sudo ln -s /opt/dokuwiki/dokuwiki-nnnn-nn-nn /opt/dokuwiki/current
</code>

=== Remove the "upgrade" link ===
<code bash>
sudo /bin/rm /opt/dokuwiki/upgrade
</code>

===== =====
After the applications runs for a while (depending on how active the installation is), execute:

<code bash>
sudo /bin/rm -Rf /opt/dokuwiki/dokuwiki-pppp-pp-pp
</code>


===== Plug-Ins =====

=== Create a link to the "new" version ===

<code bash>
sudo ln -s /opt/dokuwiki/dokuwiki-nnnn-nn-nn /opt/dokuwiki/new
</code>

=== Remove These Plug-Ins ===

<code bash>
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/authad
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/authldap
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/authmysql
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/authpgsql
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/popularity
sudo /bin/rm -Rf /opt/dokuwiki/new/lib/plugins/plugin
</code>

=== Install These Plug-Ins ===

  - Install [[https://www.dokuwiki.org/plugin:wrap|wrap]] Plugin<code bash>
wget https://github.com/selfthinker/dokuwiki_plugin_wrap/archive/master.zip
unzip master.zip
sudo mkdir -p /opt/dokuwiki/new/lib/plugins/wrap
sudo cp -R /tmp/dokuwiki_plugin_wrap-master/* /opt/dokuwiki/new/lib/plugins/wrap/
rm -R /tmp/dokuwiki_plugin_wrap-master
rm master.zip
</code>
  - Install [[https://www.dokuwiki.org/plugin:nspages|nspages]] Plugin<code bash>
wget https://github.com/gturri/nspages/tarball/master
tar zxvf master
sudo mkdir /opt/dokuwiki/new/lib/plugins/nspages
sudo cp -R /tmp/gturri-nspages-*/* /opt/dokuwiki/new/lib/plugins/nspages
rm -R /tmp/gturri-nspages-*
rm master
</code>
  - Install [[https://www.dokuwiki.org/plugin:columns|columns]] Plugin<code bash>
wget https://github.com/dwp-forge/columns/zipball/master
unzip master
sudo mkdir -p /opt/dokuwiki/new/lib/plugins/columns
sudo cp -R /tmp/dwp-forge-columns-*/* /opt/dokuwiki/new/lib/plugins/columns/
rm -R /tmp/dwp-forge-columns-*
rm master
</code>
  - Install [[https://www.dokuwiki.org/plugin:gallery|gallery]] Plugin<code bash>
wget https://github.com/splitbrain/dokuwiki-plugin-gallery/zipball/master
unzip master
sudo mkdir -p /opt/dokuwiki/new/lib/plugins/gallery
sudo cp -R /tmp/splitbrain-dokuwiki-plugin-gallery-*/* /opt/dokuwiki/new/lib/plugins/gallery/
rm -R /tmp/splitbrain-dokuwiki-plugin-gallery-*
rm master
</code>

=== Update Permissions for the Plug-In Directory ===
<code bash>
sudo chown -R www-data:www-data /opt/dokuwiki/new/lib/plugins
sudo chmod -R u-w,g-w,o-w /opt/dokuwiki/new/lib/plugins
</code>

=== Remove the "new" link ===
<code bash>
sudo /bin/rm /opt/dokuwiki/new
</code>