WordPress and 404

Today I've been working on WordPress deployment. I enabled named permalinks (when posts are addressed by the /topic-name and not by cryptic /?p=21) and my site gone crazy with 404 Page Not Found appearing for every transition from the home page.

I considered the bbPress plugin to be responsible for that, since I'd just installed it. Google Search showed a lot of discussions on the problem and some pieces of solution, but not the actual steps to fix it.

The real reason turned out to be the apache server configuration. Following are the step by step instructions for a stand-alone WordPress installation on the LAMP stack:

1. mod_rewrite MUST be enabled, so run 

sudo a2enmod rewrite

2. Virtual Host configuration for WordPress should have FollowSymLinks specified and AllowOverride option set to All. Open virtual host configuration - it should be a configuration file placed in /etc/apache2/sites-enabled/ and named like *default.

Now, directory configuration with deployed WordPress should look like this:

<Directory /var/www/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
</Directory>

In my case, all I had to do was to change None to All.

3. Restart apache web server:

sudo service apache2 restart

4. Check, that Apache has the permission to write in WordPress root folder (/var/www/ by default).

ls -l /var/www/

owner and group should be www-data. If that is not the case, execute:

sudo chown -R www-data:www-data /var/www/

5. Now check, that WordPress generates .htaccess file. Open Settings -> Permalinks in the WordPress admin console. Make some changes to these settings (say from Default to Post name) and click Save Changes. Now list the root of your WordPress deployment (this would contain folders like wp-admin and wp-content).

ls -a /var/www/

.htaccess file should be present and its content should look like:

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

At this point there shouldn't be any 404 errors and post links should look the way you've configured it.

=========
Conclusion
========= 

Now I've done with technical description and start the emotional one.

The famous WordPress installation instructions  I've used to deploy my instance don't mention any apache virtual host configuration (they mention mod_rewrite though). But I have my Permalinks settings available in my default installation and I can easily bring down the site by changing these options.

That should not be possible. I can imagine broking down the blog engine by manually editing some pages and layouts. But not by changing an innocent looking option box.

So first, the apache virtual host configuration should be included in the installation instructions. That would make the instructions less accessible and more complicated, but will eventually bring more robust site installation.

If not, it should at least show warning on the Permalinks Settings page about possible problems due to http server configuration.

But the best solution for WordPress is to detect these problems, disable the settings and provide the information on what should be configured first to unlock them. However, while it is possible to test local write permissions, the same is problematic for the apache configuration.

The similar situation appears when you are installing themes/plugins for WordPress. If you don't have a write access to the installation root it just offers you the FTP options. But it should show another disabled option - possibility of automatic HTTP install. And mention, that write access should be configured in order to enable that option.

When I see that kind of "user-friendly" interaction with the most popular blogging platform, it makes me wonder how experience differs on less popular alternatives.