Upgrading DokuWiki — Version Compatibility, Upgrade Procedures, and Troubleshooting

In this tutorial, you'll learn how to upgrade DokuWiki safely, including pre-upgrade preparation, version compatibility checking, manual and automatic upgrade procedures, troubleshooting common upgrade issues, and post-upgrade verification.

What You'll Learn

• When to upgrade DokuWiki
• Version compatibility and release names
• Pre-upgrade checklist and backup
• Manual upgrade procedure
• Automatic upgrade using the Extension Manager
• Troubleshooting upgrade issues
• Post-upgrade verification

Why It Matters

Upgrading DokuWiki gives you security patches, bug fixes, and new features. But every upgrade carries risk — plugins may break, custom templates may need updates, and configuration options may change. A structured upgrade Process minimizes downtime and prevents data loss. Skipping upgrades leaves your wiki vulnerable to known security issues.

Real-World Use

A wiki admin receives a security advisory about a vulnerability in DokuWiki 2022-07-31. They plan the upgrade to the latest release: back up the wiki, check plugin compatibility, download the new version, perform the upgrade during a maintenance window, verify all functionality, and confirm the vulnerability is patched. The upgrade takes 20 minutes with zero data loss.

Learning Path

flowchart LR
  A[Backup] --> B[Upgrading]
  B --> C[Migration]
  C --> D[Performance]
  D --> E[Security]
  E --> F[Production]

DokuWiki Release Versions

DokuWiki uses release codenames:

Check your current version:

<?php
// From any PHP file in DokuWiki
echo DOKU_VERSION;

Or look at doku.php for a version comment at the top.

Pre-Upgrade Checklist

1. Backup Everything

# Full backup before upgrade
tar -czf "pre-upgrade-backup-$(date +%Y%m%d).tar.gz" \
    data/ conf/ lib/plugins/ lib/tpl/

2. Check Plugin Compatibility

# List installed plugins with versions
php bin/plugin.php list

Check each plugin's compatibility with the target DokuWiki version. Visit the plugin's page on the DokuWiki plugin Repository.

3. Check Template Compatibility

Verify your template supports the new version. Template-breaking changes are rare but happen.

4. Review Changelog

Read the changelog for the target version:

https://www.dokuwiki.org/changes

Note any deprecated features and configuration changes.

5. Test on Staging

If possible, test the upgrade on a staging copy of your wiki before the production upgrade.

Manual Upgrade

The manual upgrade is reliable and works in all environments.

Step 1: Download New Version

cd /tmp
wget https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz
tar -xzf dokuwiki-stable.tgz

Step 2: Copy New Files

# Copy the new version's files to your wiki directory
# Overwrite core files, preserve your data and config

WIKI_DIR="/var/www/html/wiki"
NEW_VERSION="/tmp/dokuwiki-2024-02-06"

# Preserve existing data and config
cp -r "$WIKI_DIR/data" /tmp/wiki-data-backup
cp -r "$WIKI_DIR/conf" /tmp/wiki-conf-backup

# Replace core files
cp -r "$NEW_VERSION/"* "$WIKI_DIR/"

# Restore data and config
cp -r /tmp/wiki-data-backup/* "$WIKI_DIR/data/"
cp -r /tmp/wiki-conf-backup/* "$WIKI_DIR/conf/"

Step 3: Update Plugins

Check for plugin updates and install them.

Step 4: Run Upgrade Script

Access the wiki in your browser. DokuWiki automatically detects version changes and runs database-independent upgrades.

Step 5: Verify

Navigate through several pages, test editing, and verify functionality.

Automatic Upgrade via Admin Panel

The Extension Manager can perform automated upgrades.

Requirements

• Web server write access to the DokuWiki directory
• PHP zip extension enabled
• Network access to the DokuWiki download server

Procedure

1. Admin > Extension Manager
2. Click "Check for updates"
3. Click "Update" next to "DokuWiki" in the core section
4. Wait for the process to complete
5. Verify functionality

Limitations

The automatic upgrade may not work on:

• Shared hosting with restrictions
• Installations with modified core files
• Very large wikis (memory limitations)

Post-Upgrade Tasks

Verify Version

<?php
// Create a temporary info page or check the admin panel
echo DOKU_VERSION;

Test Key Features

[ ] Page viewing
[ ] Page editing and saving
[ ] Search functionality
[ ] Media upload and display
[ ] ACL permissions
[ ] User login
[ ] Plugin functionality
[ ] Template rendering
[ ] Sidebar display

Clear Cache

# Force cache rebuild
php bin/cleanup.php --cache
php bin/indexer.php -f

Re-apply Template Customizations

Check that userstyle.css and template configuration are still working.

Troubleshooting Upgrade Issues

Blank Page After Upgrade

# Check PHP error log
tail -f /var/log/apache2/error.log

# Common causes:
# - PHP version too old for new DokuWiki
# - Missing PHP extensions
# - Memory limit too low

Plugin Errors

# Disable all plugins to identify the culprit
mv lib/plugins/* lib/plugins-disabled/

# If wiki works, re-enable plugins one by one

Template Issues

Switch to the default template temporarily:

<?php
// conf/local.php
$conf['template'] = 'dokuwiki';

ACL/Login Problems

# Reset ACL to open temporarily
# conf/acl.auth.php
* @ALL @8

# After debugging, restore original ACL

Upgrading Plugins

Check for plugin updates after upgrading core:

php bin/plugin.php checkupdates
php bin/plugin.php list

Update plugins individually or replace them manually.

Version Compatibility Matrix

Always check your PHP version before upgrading:

php --version

Common Mistakes

1. Upgrading without a backup: If the upgrade fails, you need a rollback plan. Always back up before upgrading.
2. Ignoring plugin compatibility: An incompatible plugin can break the entire wiki or cause errors on every page. Check plugin compatibility first.
3. Upgrading on production without testing: Test the upgrade on a staging copy. Production upgrades should be routine, not adventurous.
4. Skipping the changelog: A single deprecated configuration option can cause unexpected behavior. Read what changed.
5. Not updating plugins after core upgrade: Old plugins may not work with new DokuWiki versions. Update them as part of the upgrade process.

Practice Questions

1. What steps should you take before upgrading DokuWiki to ensure a safe upgrade?
2. What is the difference between a manual upgrade and an automatic upgrade via the Extension Manager?
3. After upgrading, what key features should you verify before declaring the upgrade successful?
4. Challenge: Write a comprehensive upgrade script that: backs up the existing installation, downloads the latest DokuWiki version, performs the upgrade, updates all plugins (checking for compatibility), clears the cache, rebuilds the search index, runs a verification checklist (page view, edit, search, login, upload), and logs all actions with timestamps. Test the script on a staging environment by performing an upgrade, then test the rollback procedure.

FAQ

Mini Project

Goal: Perform a complete upgrade cycle on a staging wiki.

1. Check your current DokuWiki version
2. Review the changelog for the target version
3. Back up the staging wiki completely
4. Check plugin and template compatibility
5. Perform the upgrade (manual method)
6. Clear cache and rebuild the index
7. Test all key features (page view, edit, search, upload, login)
8. Test each plugin individually
9. Document any issues encountered
10. Practice the rollback procedure

What's Next

Now you can upgrade DokuWiki. Learn about migrating from other wikis to DokuWiki from MediaWiki and other platforms.