How to Change the Document Root in WHM

When you type a URL into a web browser, you’re referencing a specific folder. Sometimes, the folder name is expressly mentioned in the URL and sometimes it’s not. When you enter a top-level domain name such as example.com, the server has to decide which folder to show you. In the overwhelming majority of cases by default, this folder is known as “public_html”. in an earlier article, we saw how to change the default directory page that controls which file is displayed for a particular folder. But how do you change the default directory itself?

The answer lies in a special file located deep in the WHM hierarchy called httpd.conf. It’s an extremely important file that is automatically generated from a number of templates and controls a large part of Apache’s configuration. There is a directive in it known as “DocumentRoot” controlling the default folder for every domain. But modifying httpd.conf directly is dangerous, so we’re going to have to use include files. Here’s a step-by-step tutorial:

Creating the New Document Root

I have a default index.html file located within the “public_html” folder of my cPanel installation for my domain. When I visit the primary URL ihavetoretire.com, it’s displayed because it’s the only file in the public_html directory.

What I’m going to do now, is create a new folder at the same hierarchy as public_html called “new_root” and I place a similar index.html file into it:

However, I change the contents of this new index.html file so that the text reflects the fact that it’s in a new directory. Using the cPanel file editor, you can see below that it is indeed located within “new_root” and the text has been changed to match it.

At the end of this tutorial, the new index.html file should display instead of the old one.

Configuring httpd.conf

Using a file editor of your choice, navigate to the following directory:

/usr/local/apache/conf

Over here, you’ll see the all important file httpd.conf.

While we’re not going to edit it directly, it’s useful to open it up and see exactly what we want to change. Scroll down until you come across a tag with

<VirtualHost xxxxx>
ServerName yourdomain.com

In the example below, you can see that my httpd.conf file sets a parameter called “DocumentRoot” to “/home/bhagwad/public_html”.

You may think that it’s a simple affair to merely change this to “/home/bhagwad/new_root” instead. But this is a dangerous thing to do. To drive the point home, just read the huge warning in capital letters above the VirtualHost tag. So what do we do if we need to change it? The answer is “include files”.

Continue scrolling down within the same <VirtualHost> tag until you reach a line which says something like:

# To customize this VirtualHost use an include file at the following location
# Include "/usr/local/apache/conf/userdata/std/2_4/bhagwad/ihavetoretire.com/*.conf"

Of course, the name will be different for you depending on your user name and domain name, so make a note of the exact directory location in the second line. This points to a “.conf” file in the specified directory which will contain additional instructions to be included into httpd.conf. The presence of this file along with the command we will run afterwards will comment out the “Include” directive.

Keeping in mind the above location, and run the following commands modified appropriately:

mkdir -p /usr/local/apache/conf/userdata/std/2_4/bhagwad/ihavetoretire.com

cd /usr/local/apache/conf/userdata/std/2_4/bhagwad/ihavetoretire.com

In this new directory, I create a configuration file called “newroot.conf” with just a single line:

DocumentRoot /home/bhagwad/new_root

When this file gets included in httpd.conf, this new directive will take precedence over the older one we saw above. Once you’ve created this file and saved it, we need to activate the “include” files with the following SSH command:

/scripts/ensure_vhost_includes --all-users

This will rebuild httpd.conf and restart Apache as well. Now it’s time to test whether or not our changes have taken effect. If so, the new DocumentRoot directive will redirect ihavetoretire.com to “new_root” in which my new index.html file resides. So I type the URL into my browser and get the following result:

It works! We’ve achieved this without modifying the httpd.conf file directly and included our own directions in a safe and scalable manner in order to change the document root in WHM.