Wikka and mod_rewrite


The Apache webserver has a module called mod_rewrite. mod_rewrite "rewrites" URLs so it can do things like translate the URL http://wikkawiki.org/wikka.php?wakka=DotMG into http://wikkawiki.org/DotMG. This gives us nice, short, and user-friendly URLs to use with Wikka while internally Wikka works with the "full" URL.
Wikka works with or without mod_rewrite but this page will guide you through the steps required to create nicer URLs by activating URL rewriting functionality.

Requirements

  1. The major requirement is that Wikka is installed on a system with Apache as the web server. (Some other web servers, like lighttpd, support similar functionality, but IIS definitely does not.)
  1. Also, mod_rewrite must be enabled (not the case on many hosted systems)
  1. Finally, either .htaccess configuration must be allowed (not the case on many hosted systems) - because Wikka by default uses .htaccess files in directories to enable/disable URL rewriting - or you must have root access and be able to edit the Apache configuration (httpd.conf) directly (only on dedicated servers or some virtual private/dedicated systems).

Configuration

During installation, Wikka will try to figure out if mod_rewrite is available. If Wikka does not detect mod_rewrite, it's possible to manually configure Wikka to use it after installation.

Follow this simple instruction:

Change these lines:
    "base_url" => "http://my.domain.com/wikka.php?wakka=",
    "rewrite_mode" => "0",


to this:
    "base_url" => "http://my.domain.com/",
    "rewrite_mode" => "1",


That's it. Notice the small change. We are just removing "wikka.php?wakka=" and then setting rewrite_mode to 1. Note that the two configuration settings must always match - if not, you'll end up with strange errors and pages not found.

Note: this may not work when you installed wikka in some subdirectory. In that case, edit .htaccess and add the following line, right after the line that reads RewriteEngine on:
RewriteBase /your/subdirectory/name


Even if URL rewriting is used in Wikka, the long form of the URLs will continue working so you don't need to change any links with long URLs you may already have when switching to using mod_rewrite.

Troubleshooting

If after following the instruction above mod_rewrite is still not working, first make sure that Wikka is actually running on Apache. Creating a page with just and calling this page up in the browser will give a host of information about the environment PHP is running in.

Next, check to make sure mod_rewrite has been activated in your httpd.conf file:
LoadModule rewrite_module    /path/to/apache/modules/mod_rewrite.so
AddModule mod_rewrite.c


Also, make sure that in your Apache httpd.conf file that you have enabled FollowSymLinks in the Options configuration section.
 # The Options directive is both complicated and important.  Please see
# http://httpd.apache.org/docs-2.0/mod/core.html#options
# for more information.
#
    Options Indexes FollowSymLinks


In addition, the directive "AllowOverride" must be set to "All" before requests to access .htaccess are honored:
#
# This controls which options the .htaccess files in directories can
# override. Can also be "All", or any combination of "Options", "FileInfo",
# "AuthConfig", and "Limit"
#
    AllowOverride All

Note that there might be some security issues that need to be investigated when setting this parameter to anything other than "None". Consult the appropriate Apache documentation for details.

Check your logs! For instance, if you see a "File does not exist: /some/internal/path/to/HomePage" in your error_log, check wikka.config.php and make sure base_url is set to the correct pathname to access your wiki, and that it includes a trailing slash (/)! For example, if you normally access your wiki using http://yourdomain.com/mywiki , then your base_url must be set to:
"base_url" = "http://yourdomain.com/mywiki/",


Hosted server
If your server is Apache, there are two possibile causes why mod_rewrite may not work: Either your web host does not have mod_rewrite configured so that you can use it, or .htaccess is ignored in directories. (You may try asking your host to enable both - if that doesn't work you'll have to do with long URLs.)

(Virtual) Private Server
If you are controlling your own server and mod_rewrite is enabled, there are two configuration options:
  1. Make sure .htaccess files in directories are supported. This is the easiest way to enable Wikka to use URL rewriting. Wikka uses a .htaccess for rewrite configuration in the installation directory as well as in the following subdirectories:
The .htaccess file in the installation directory enables mod_rewrite while the other ones disable it again because these directories contain files that are directly linked to from generated HTML pages.
  1. If you prefer, you can reproduce the rewriting rules for the installation directory (from the main .htaccess file) directly in your httpd.conf file. If you do this, make sure that either .htaccess is enabled for the mentioned subdirectories (and the .htaccess files are present there) or that you explicitly turn off rewriting in the subdirectories mentioned above by means of Directory directives.

Known issues

Some Apache versions for Windows have a bug that will lowercase all URLs when using mod_rewrite. This is a problem in Wikka, specifically when creating new pages. We're looking into the possibility of creating a workaround for this.


CategoryEN CategoryReview
There are no comments on this page.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki