I've been playing around with Habari, and so far I've tested the install on three different machines. One of Habari's requirements is Apache's mod_rewrite, which allows URLs from a client to be rewritten on the server. This means that a browser can request a pretty URL, such as
http://www.example.com/habari/really-interesting-post and it will be redirected on the server to a script that returns the post with the slug
really-interesting-post. Mark Jaquith has written a good article about this in relation to WordPress.
When mod_rewrite isn't working, Habari will give you the following error message during installation (Habari is under pretty intense development at the moment, so this message may change):
You might want to make sure mod_rewrite is enabled and that AllowOverride is at least set to FileInfo for the directory where .htaccess resides.
404 Not Found Not Found The requested URL /habari/htdocs/ajax/check_mysql_credentials was not found on this server.
The installer made a request to
ajax/check_mysql_credentials under the Habari installation. That file doesn't exist, but as I said above, to keep URLs consistent Habari maps pretty URLs to their real location using mod_rewrite. In this case, mod_rewrite isn't working, so an error is returned.
Now, mod_rewrite is very widely available, but isn't compiled into Apache by default. It's unlikely you'll get this error if you're using a hosted service, but you might if you've installed Apache yourself. First, you have to make sure that mod_rewrite is enabled. There are other configurations that will work, but if you compile Apache with
./configure --enable-module=rewrite --enable-shared=rewrite mod_rewrite will be installed.
So what's this about
.htaccess? In its root directory Habari uses an
.htaccess file, which is an Apache configuration file, to set up the rewriting rules. The default installation of Apache doesn't allow per directory configuration files, so if mod_rewrite is working it's likely that Habari can't rewrite the URL because it can't use the
AllowOverride is an Apache configuration directive used in the main configuration file,
conf/httpd.conf in your Apache installation, that tells Apache what sort of commands are allowed to be used in an
.htaccess file. Apache needs to be told that it's okay to use an
.htaccess file in the directory where Habari is installed. Your
httpd.conf will contain something like the following:
<Directory "/usr/local/apache2/htdocs"=""> Options Indexes FollowSymLinks AllowOverride None Order allow,deny Allow from all </Directory>
Directory container specifies a directory where these directives apply. This is for the
DocumentRoot, and also applies to its descendents. As
AllowOverride None is set in
.htaccess files will be read in the Web directory tree. To fix this we either change the directive to
AllowOverride FileInfo in the
DocumentRoot or we can create another
Directory container specifically for our Habari installation and set
Don't forget to restart Apache!
If you're interested in learning more, Sitepoint has an introduction to mod_rewrite rules, including a simple test to see if mod_rewrite is working.
[Update: mod_rewrite isn't included in Apache by default. I've corrected the error and expanded.]