The default Apache document root on Linux systems is usually /var/www/html/. This directory contains the main web content served by the Apache web server. However, there are many reasons why you may need to change the document root to a different location.

This guide provides web administrators and developers with advanced techniques and troubleshooting tips for changing the Apache document root on Linux. Whether you‘re migrating to new storage, hosting multiple sites, or just looking for more flexibility, modifying the document root is a common task.

Change Document Root in Apache

Using Virtual Hosts and Mass Virtual Hosting

The easiest way to use multiple Apache document roots is through virtual hosts. This allows you to serve different content for separate domains and subdomains from the same Apache instance.

To configure virtual hosts with different document roots:

• Create virtual host containers in the Apache configuration files, either in /etc/httpd/conf/httpd.conf or individual .conf files inside /etc/httpd/conf.d/.
• Specify unique ServerName, ServerAlias, and DocumentRoot directives for each virtual host.

For example:

<VirtualHost *:80>
  ServerName www.site1.com
  DocumentRoot /var/www/site1
</VirtualHost>

<VirtualHost *:80>
  ServerName www.site2.com 
  DocumentRoot /var/www/site2
</VirtualHost>

This separates the content for each website into isolated directories.

For managing a large number of virtual hosts, Apache provides dynamic mass virtual hosting using modules like mod_vhost_alias. This auto-generates virtual host configs instead of manually specifying each one.

Using Symbolic Links

Another option is to keep the main document root in place but use symbolic links to point parts of the website hierarchy to directories outside of /var/www/html/:

ln -s /mnt/volume1/site1 /var/www/html/site1

This introduces flexibility without disrupting the main DocumentRoot location.

Employing .htaccess Rules and mod_rewrite

If you don’t have access to Apache configuration files, you can also use .htaccess rewrite rules and mod_rewrite to redirect requests to new directories.

For example:

RewriteEngine On
RewriteRule ^/$ /var/www/newroot/ [L]

This transparently maps requests from the old document root to the new location.

Permissions and Ownership

When changing the document root location, especially when moving outside the default /var/www/ hierarchy, check ownership and permissions on the new root directory.

Use chown to grant ownership to the Apache user and group (often www-data or apache), and chmod to ensure the web server has execute and read access.

Check Apache Configuration Syntax

Syntax errors in Apache’s configuration files can prevent the proper document root from being set. Use Apache’s configtest command to check for errors:

apachectl configtest

This will catch mistakes before trying to restart the web server.

Verify Functionality and Remove Old Root Content

Once the document root is changed, thoroughly test the affected websites and applications. Ensure proper functionality, then delete the content from the original location when ready. This will free resources on the filesystem.

Troubleshooting

Permissions Issues

Permission errors may occur after changing the document root. The Apache user (often www-data or apache) must have the necessary permissions to read and execute files in the new document root directory. Adjust permissions and ownership with chmod and chown commands.

Configuration Errors

Syntax errors in Apache’s configuration files can prevent the server from starting. Use the apachectl configtest command to check for syntax errors before restarting Apache.

404 Not Found Errors

If you encounter 404 errors after changing the document root, ensure that the DocumentRoot and <Directory> directives in your configuration files are correct and the directory exists.

403 Forbidden Errors

A 403 Forbidden error may occur if Apache is configured to deny access to the new document root. Check the <Directory> directive for the new document root in your configuration files, ensuring it allows access with Require all granted or similar permissions.

Conclusion

Changing the Apache document root allows you to utilize different storage devices, host multiple websites more efficiently, and gain more control over your web server environment. Carefully planned virtual hosts, symbolic links, .htaccess rules, and configuration changes make modifying the document root straightforward. However, troubleshooting permissions issues, checking configurations, and verifying functionality are vital steps to avoid disruptions. With attention to detail, you can transition document roots smoothly.