These instructions detail how to install DokuWiki on our Debian GNU/Linux system. We're currently running the 2013-12-08 version of DokuWiki.
We aren't using the Debian packaged DokuWiki, because we want to keep up with the latest versions.
Our installation is rather unusual. We install DokuWiki into /usr/local/share
, and mostly use soft links to point our web sites at that directory. This is somewhat similar to the way the Debian packaged version does it, but much simpler. This method allows for easier upgrades, as well as sharing the code amongst multiple sites. On the other hand, it prevents through-the-web installation of plugins.
We also allow mixing static content into the site. To do so, simply place the static content in the static
directory, and it will appear within the site. This makes it a lot easier to take a static site and add DokuWiki on top.
Download and unpack the program:
DOKUWIKI_VERSION='2016-06-26a' wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-$DOKUWIKI_VERSION.tgz tar xfz dokuwiki-$DOKUWIKI_VERSION.tgz rm dokuwiki-$DOKUWIKI_VERSION.tgz sudo mkdir -p /usr/local/share/dokuwiki sudo rm -f /usr/local/share/dokuwiki/$DOKUWIKI_VERSION sudo cp -r dokuwiki-$DOKUWIKI_VERSION /usr/local/share/dokuwiki/$DOKUWIKI_VERSION
We're going to use .htaccess
to enable mod_rewrite
for nice looking URLs. NOTE: Be sure to update the auto_prepend_file
path.
sudo sh -c 'cat > /usr/local/share/dokuwiki/.htaccess' <<'EOF' ## We don't need to allow index files. We do need to allow symlinks though. Options -Indexes +FollowSymLinks ## Make sure nobody gets the htaccess, README, COPYING or VERSION files <Files ~ "^([\._]ht|README$|VERSION$|COPYING$)"> Order allow,deny Deny from all Satisfy All </Files> ## Add a configuration file to define the top-level directory for the given instance. php_value auto_prepend_file '/usr/local/share/dokuwiki/preconfig.php' ## Enable nice-looking URLs. RewriteEngine on # Allow static content from outside of DokuWiki. RewriteCond %{DOCUMENT_ROOT}/static/%{REQUEST_URI} -f RewriteRule .* static/%{REQUEST_URI} [QSA,L] RewriteRule ^static/.* - [QSA,L] # Real pages that we need to allow access to. Note that we don't use RewriteCond %{REQUEST_FILENAME} !-f for these. RewriteRule ^doku.php - [QSA,L] RewriteRule ^feed.php - [QSA,L] RewriteRule ^lib/ - [QSA,L] # Media and other supporting files. RewriteRule ^_media/(.*) lib/exe/fetch.php?media=$1 [QSA,L] RewriteRule ^_detail/(.*) lib/exe/detail.php?media=$1 [QSA,L] RewriteRule ^_export/([^/]+)/(.*) doku.php?do=export_$1&id=$2 [QSA,L] # Default (home) page. RewriteRule ^$ doku.php?id=home [QSA,L] # All other pages. RewriteRule (.*) doku.php?id=$1 [QSA,L] EOF
We need to create a shim to set the top-level directory for the site that's loading.
sudo sh -c 'cat > /usr/local/share/dokuwiki/preconfig.php' <<'EOF' <?php if ( $_SERVER['DOCUMENT_ROOT'] == '' ) { define ('DOKU_INC', getcwd() . '/'); } else { define('DOKU_INC', $_SERVER['DOCUMENT_ROOT'] . '/'); } EOF
# Ensure template directory exists. sudo mkdir -p /usr/local/share/dokuwiki/templates sudo chown $USER /usr/local/share/dokuwiki/templates # Get the vector template. wget -O vector.tgz http://andreas-haerter.com/downloads/dokuwiki-template-vector/latest tar xfz vector.tgz -C /usr/local/share/dokuwiki/templates # Get the greensteel template. wget -O greensteel.zip http://syntaxseed.com/project/dokuwikithemegreensteel/download/ unzip -d /usr/local/share/dokuwiki/templates greensteel.zip # Replace greensteel's green gradiant with a blue gradiant. wget -O /usr/local/share/dokuwiki/templates/greensteel/images/background_repeat.gif 'http://i-tools.org/gradient/exec?submit=1&type=topbottom&size=100&colors=020A75+404DD0&reverse=0&rotate=0&format=gif&alphacolor=%23000000' # Make greensteel's background match the gradiant. Make its links match the background color. cat > /usr/local/share/dokuwiki/templates/greensteel/style.local.ini <<'EOF' [stylesheets] css/custom.css = screen [replacements] __background_site__ = "#404DD0" __link__ = "#404DD0" __existing__ = "#404DD0" EOF # Make sure we can read the footer when using the greensteel template. cat > /usr/local/share/dokuwiki/templates/greensteel/css/custom.css <<'EOF' #dokuwiki__footer { background: white; } EOF # Replace greensteel's logo with a transparent 1x1 icon -- effectively removing the logo. wget -O /usr/local/share/dokuwiki/templates/greensteel/images/logo.png http://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png # Install some custom templates that we maintain in GitHub. git clone git@github.com:boochtek/dokuwiki-templates.git /usr/local/share/dokuwiki/templates # Make sure the shared templates are seen by the current version of DokuWiki. TEMPLATES=$(\cd /usr/local/share/dokuwiki/templates/ && ls --ignore README.md) for template in $TEMPLATES; do sudo ln -sf /usr/local/share/dokuwiki/templates/$template /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/lib/tpl/ ; done
Copy and link the DokuWiki files as appropriate into the site.
SITE='wiki.boochtek.com' cd /var/www/$SITE if [ ! -e conf ]; then cp -r /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf . fi if [ ! -e data ]; then cp -r /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/data . fi chgrp -R www-data conf data chmod -R g+w conf data mkdir -p public static sudo ln -s /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/{bin,inc,lib,vendor,doku.php,feed.php} public/ sudo ln -s /usr/local/share/dokuwiki/.htaccess} public/ (cd public; sudo ln -s ../{conf,data,static} .) # Make sure we've got a sitemap that the web server can update. touch data/cache/sitemap.xml.gz chgrp www-data data/cache/sitemap.xml.gz chmod g+w data/cache/sitemap.xml.gz
Edit the conf/local.php
file to look like this (make sure it doesn't have any blank lines outside the PHP tags):
<?php $conf['title'] = 'BoochTek Wiki'; $conf['start'] = 'home'; // Name of the default page. $conf['template'] = 'default'; $conf['superuser'] = 'admin'; // Set the admin user. $conf['userewrite'] = 1; // We're using mod_rewrite to make pretty URLs. $conf['useslash'] = 1; // Use slashes to separate namespaces, instead of colons. $conf['target']['interwiki'] = ''; // Don't pop up a new window for Interwiki links. $conf['target']['extern'] = ''; // Don't pop up a new window for external links. $conf['breadcrumbs'] = 1; // Only show 1 previous page. $conf['htmlok'] = 1; // Allow editing of raw HTML tags. $conf['usewordblock'] = 1; // Block posts using "banned" words, to reduce spam. $conf['mailguard'] = 'visible'; // Use "name [at] domain [dot] com" format to display email addresses. $conf['typography'] = 0; // Don't convert quotes to fancy version. $conf['license'] = 'cc-by'; // License of all content. See conf/license.php and conf/license.local.php for choices. $conf['showuseras'] = 'username'; // Show users' full names, no email addresses or login names. $conf['cssdatauri'] = 1024; // Maximum byte size of small images to embed into CSS. $conf['useacl'] = 1; // Use ACLs to restrict who can edit pages on the site. $conf['openregister'] = 0; // Users may NOT register themselves. $conf['compress'] = 0; // Compressing CSS (and JS) was causing problems.
We deactivate the automatic conversion of certain character combinations into different symbols since this destroys the ability to cut/paste commands and sample configuration data from the documentation. For example, DokuWiki was converting –inet=1
into –inet=
which resulted in a single dash when cut/pasted from the browser to another window, with the copied command failing.
mv conf/entities.conf conf/entities.conf.out
We were getting a lot of spam on the wiki, so we enabled the wordblock feature, with blocklist updates downloaded from WikiMedia every day.
sudo curl http://meta.wikimedia.org/wiki/Spam_blacklist?action=raw 2>/dev/null | grep -v '<pre>' > /var/www/wiki.boochtek.com/wordblock.conf sudo rm /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf sudo ln -s ../../wordblock.conf /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf sudo sh -c 'cat > /etc/cron.daily/dokuwiki-spam-blocklist-download' <<EOF # Back up the existing wordblock file. cp /var/www/wiki.boochtek.com/wordblock.conf /var/www/wiki.boochtek.com/wordblock.conf.BAK # Download the latest spam_blacklist from WikiMedia. curl http://meta.wikimedia.org/wiki/Spam_blacklist?action=raw 2>/dev/null | grep -v '<pre>' > /var/www/wiki.boochtek.com/wordblock.conf # If the file we downloaded is less than 10000 lines, revert to the backup. if [ `wc -l /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf | cut -d' ' -f1` -lt 10000 ] ; then mv /var/www/wiki.boochtek.com/wordblock.conf.BAK /var/www/wiki.boochtek.com/wordblock.conf fi EOF sudo chmod +x /etc/cron.daily/dokuwiki-spam-blocklist-download
Installed the following plugins:
Browse to the wiki and make sure it shows up.
Try to edit a page. Make sure it saves OK.
Make sure history feature ("Old revisions") works
With multiple versions of DokuWiki installed into /usr/local
, we can have multiple versions installed at the same time, and we can have different sites running different versions. So upgrading consists primarily of installing a new version, the pointing each site at the new version of the code. The installation portion is as follows (basically the same as above, but it's broken up into a couple pieces above):
# Define the version that we're upgrading to. DOKUWIKI_VERSION='2017-02-19a' # Download and install the new version. wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-$DOKUWIKI_VERSION.tgz tar xfz dokuwiki-$DOKUWIKI_VERSION.tgz rm dokuwiki-$DOKUWIKI_VERSION.tgz sudo mkdir -p /usr/local/share/dokuwiki sudo rm -f /usr/local/share/dokuwiki/$DOKUWIKI_VERSION sudo cp -r dokuwiki-$DOKUWIKI_VERSION /usr/local/share/dokuwiki/$DOKUWIKI_VERSION # Make sure the shared templates are seen by the current version of DokuWiki. TEMPLATES=$(\cd /usr/local/share/dokuwiki/templates/ && ls --ignore README.md) for template in $TEMPLATES; do sudo ln -sf /usr/local/share/dokuwiki/templates/$template /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/lib/tpl/ ; done
Be sure to read the changes made in the new release. Make sure you follow any directions specific to the new release. Also read through the dokuwiki/$DOKUWIKI_VERSION/conf/dokuwiki.php
file to look for any new config options. Make any necessary changes to conf/local.php
for each site.
When you're ready to upgrade the sites:
# Define the version that we're upgrading to. DOKUWIKI_VERSION='2017-02-19a' # Define the site we're updating. SITE='wiki.boochtek.com' cd /var/www/$SITE # First we make a full backup of the existing site before upgrading, just in case. BACKUP_DIRS=$(ls -d conf data static public 2>/dev/null) sudo tar cfz BACKUP-$(date +%Y%m%d).tgz $BACKUP_DIRS # Link to the new version of DokuWiki. ln -sf /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/{bin,inc,lib,vendor,doku.php,feed.php} public/ ln -sf /usr/local/share/dokuwiki/.htaccess public/ for file in $(cd /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf >/dev/null ; ls); do ln -sf /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf/$file conf/$file done # Get any updates to the help pages (in the ''wiki'' namespace). rm -rf data/pages/wiki cp -a /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/data/pages/wiki data/pages/wiki # Delete the old cache and index, since they can be regenerated, and the formats may have changed between versions. sudo rm -rf data/cache/* rm -rf data/index/* # Regenerate the site index. (cd public ; php -d auto_prepend_file='/usr/local/share/dokuwiki/preconfig.php' bin/indexer.php -c) chmod -Rf g+w conf data # Make sure we've got a sitemap that the web server can update. touch data/cache/sitemap.xml.gz chgrp www-data data/cache/sitemap.xml.gz chmod g+w data/cache/sitemap.xml.gz
Test the site. Make sure you can browse to a few different pages. Also make sure you can edit and save a page. Check out the search feature, backlinks, and old revisions.
Since the wordblock feature didn't stop the spammers from changing our pages, we had to enable ACLs and logon accounts.
Create the conf/users.auth file:
cd /var/www/wiki.boochtek.com/public sudo touch conf/users.auth.php sudo chown www-data:www-data conf/users.auth.php sudo chmod 440 conf/users.auth.php
Add an admin account in the file (replace $WIKI_ADMIN_PWD with real password):
sudo sh -c "echo admin:`echo -n $WIKI_ADMIN_PWD | md5sum | awk '{print \$1;}'`:Administrator:webmaster@sluug.org:admin,users >> conf/users.auth.php"
Create the conf/acl.auth.php
file:
sudo cp conf/acl.auth.dist conf/acl.auth.php sudo chown www-data:www-data conf/acl.auth.php sudo chmod 440 conf/acl.auth.php
Edit the conf/acl.auth.php
file to look something look this:
* @ALL 1 * @user 15 * @admin 255
robots.txt
file for the Wiki site.indexdelay
setting.robots
meta
tag is the way we want it.