HOWTOs / Making sure .htaccess and mod_rewrite are working as they should

Note: You are currently reading the documentation for Bolt 5.0. Looking for the documentation for Bolt 5.2 instead?

Bolt makes extensive use of a common feature called 'url rewriting'. This basically means that you can request a pretty url like /page/about-this-website in your browser, and behind the scenes your web server will just 'translate' this to run the index.php with the correct parameters, so that Bolt can produce the correct page for you.

This doesn't work out-of-the-box on all web servers, but it is a hard requirement for using Bolt. If you're reading this page, you are likely in the process of setting up Bolt and after requesting the first page, you got redirected to the page /bolt/userfirst, where you saw the following error message:

One of the three following possibilities is giving you problems:

• You've misplaced the .htaccess file
• Apache ignores .htaccess altogether
• Mod_rewrite is not enabled

Test if .htaccess is working¶

The simplest way to test if apache uses your .htaccess file, or if it otherwise ignores it, is to intentionally break it.

Edit the .htaccess file, so the first line reads 'Test.':

Test.

# Set the default handler
DirectoryIndex index.php index.html index.htm

...

Now, if you refresh the page in your browser, you should see an error page like this:

If you see this error, that's actually good! This means that Apache is parsing the .htaccess file, and it encounters the error we've put in there! So far, so good!

If you do not see an 'Internal Server Error', your Apache setup ignores the .htaccess file, and you need to fix that. Generally, Apache ignores the .htaccess file because of the following Apache configuration AllowOverride none. Check your virtual host configuration and add/amend to AllowOverride All.

Example:

    <Directory /var/www/site/example.com/>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

If you are not sure if the .htaccess file exists and is readable, download our test script:

• Download the script here: htaccess_tester.php on GitHub
• Rename it to htaccess_tester.php, if needed.
• Place it in the folder where you've put Bolt.
• Open it in the browser with the URL. (so, make sure you're not accessing it as a file://)
• If you get an error, you will need to fix it by making sure the .htaccess file exists and is readable.

This is correct:

Test if mod_rewrite is working¶

To test if mod_rewrite is working correctly, do the following:

• Download the script here: htaccess_tester.php on GitHub
• Rename it to htaccess_tester.php, if needed.
• Place it in the folder where you've put Bolt.
• Create a .htaccess file with the contents as below.

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^.*$ htaccess_tester.php
</IfModule>

• In your browser, open /test, with the correct domain name. So, it should look like http://localhost/test or http://example.org/test.
• If you see the following, it works! If you see something else, you will need to fix that.

This is correct:

My htaccess is broken? What do?¶

There are a plethora of reasons why it might not work on your system, and these reasons vary so wildly, that we can't give an exhaustive solution for that. That said, here are a few pointers that might help you fix it:

Enable .htaccess in your httpd.conf or apache.conf¶

It's unusual, but possible that .htaccess is not enabled on your site. If you are hosting it yourself, it's easy enough to fix. Open your httpd.conf or apache.conf in a text editor, and locate the <Directory> section:

<Directory "/var/www/htdocs">
    AllowOverride None

Change the AllowOverride line to:

    AllowOverride All

Be sure to restart Apache after making any modifications to this file. Now, your .htaccess should work. You can also make this change inside a virtual host, which would normally be preferable, but that depends on the way Apache is set up.

If your site is hosted elsewhere, check your control panel (Plesk, DirectAdmin, CPanel, whatever) to see if you can enable .htaccess there. If not, contact your hosting provider to do it for you.

Enable mod_rewrite in Apache¶

There are a number of ways to enable mod_rewrite, in case it's not yet enabled on your setup. See this Stack Overflow thread for various ways this may be done on different setups: How to enable mod_rewrite for Apache 2.2.

Inspect Apache's logfiles¶

Apache logs a lot of stuff. Inspect the 'access' and 'error' logs generated by Apache to see if they contain valuable information. A common location for these files is /var/log/apache2/, but it might be in a different path on your system. Check your apache .conf file to see where these files might be hiding.

Enabling Rewritebase¶

If you're setting up Bolt in a subfolder, you might have to uncomment the line for the RewriteBase setting.

Change

  # Some servers require the RewriteBase to be set. If so, set to the correct folder.
  # RewriteBase /

to:

  # Some servers require the RewriteBase to be set. If so, set to the correct folder.
  RewriteBase /

Move your site to the 'top level'¶

If you're setting up Bolt in a subfolder and the previous tip doesn't work, you might try setting up Bolt in it's own subdomain, since that usually gives less problems. So, instead of using http://example.org/testingbolt, set it up as http://testingbolt.example.org/.

Contact your webhost¶

Ask your webhost what might be wrong. The more info you give them, the bigger the chance that they might be able to help you out.

Use a pre-configured build of Apache¶

If you're setting up Apache on your own computer, and it's turning out to be hard to configure, you should consider using XAMPP (Windows), MAMP (OS X) or AMPPS (Windows, OS X, Linux).

Use Nginx instead¶

If you're fed up with Apache's shenanigans, you might consider ditching it in favor of Nginx. Nginx is a high-performance web server, that's actually easier to configure than Apache.