How to Change the documentroot in WHM/cPanel

I'm going to describe how to change the document root on an Apache web server using WHM/cPanel. To follow the guide below you should already be familiar with WHM/cPanel, and basic web server administration.

Of course, your web server may be configured differently so the instructions below are just a guide. If you are not comfortable modifying these files yourself contact tech support at your web hosting company.

You will need to have access to your Apache web server configuration files, be comfortable navigating through directories in the terminal, and using the vi editor, or some other text editor, to modify files on your web server.

In particular, I'm going to focus on configuring the server for a new Drupal 8/9 installation. The specifics of installing Drupal will come in a later post.

Why do we Need to Change the Documentroot?

Drupal 8 and onward represent a significant departure from previous versions of Drupal. With earlier versions Drupal was installed in the 'publlic_html' directory. With the release of Drupal 8, it's recommended to install Drupal in the 'public_html/web' directory.

You can name the directory something other than 'web', but for this post we will use the default 'web' directory created during the installation of the Drupal 8/9 core-recommended profile.

The problem is that most web servers are configured to use 'public_html' as the documentroot by default, and there is no way to change it within the CPanel interface.

Additionally, many web hosting companies will not allow the documentroot to be changed on a shared hosting account so if you must change the documentroot and your hosting company will not allow it you will need to switch to a host that allows you more control, or upgrade from a shared hosting account to a VPS.

I'm going to talk a little bit about why we change the documentroot for Drupal, but I'm not not going to get into the specifics of installing Drupal, just the web server configuration to prepare for the installation.

Advantages to Changing the documentroot for a Drupal Installation

There are a number of reasons for why Drupal 8/9 are installed in a sub-directory.

1. Installing in a sub-directory maintains a clean file structure with your Drupal files kept separate from your web server system files.
2. You will be creating a private and a public directory as part of your Drupal installation and it is recommended, for security reasons that these directories, along with the vendor directory are not in the publicly accessible documentroot.

Modifying the documentroot - Dev vs. Production

Modifying the documentroot is not a problem in a local dev environment because you can easily set up virtual hosts to point to the directory the site is installed in. However, this is not easy to configure on the live server.

One option is .htaccess redirects but I've found these to be cumbersome to implement, and they do not play well with other redirects such as redirecting from https://example.com to https://www.example.com.

In my case, I have 2 VPS servers and since I manage the servers I can make whatever changes I need to the configuration. However, I have customers whose sites are hosted on shared hosting services with other companies and they are not able to change the documentroot.

Change the documentroot in Apache using the WHM Terminal Screen

On my VPS server, in WHM, I make the changes in the Terminal. You will be modifying an existing account so the account must be created first in WHM. Once you have created the account you can  create the 'web' sub-directory in 'public_html.'

You are now ready to change the documentroot. In your WHM account go to Server Configuration > Terminal.

Edit the required user account following the command below, replacing the 'username' with the cPanel account username and 'example.com' with the domain name for the account you want to modify:

vi ../var/cpanel/userdata/username/example.com

Find the following two lines in the example.com file:

documentroot: /home/username/public_html

path: /home/username/public_html/cgi-bin

Change the documentroot of your primary domain from 'public_html' to 'public_html/web' and the path to include the 'web' directory. The document root and path should now look like this:

documentroot: /home/username/public_html/web

path: /home/username/public_html/web/cgi-bin

Save the updated file.

Then delete the cache file for the domain:

# rm -vf /var/cpanel/userdata/username/example.com.cache

If the domain has an SSL certificate installed you will also need to modify the documentroot line in the example.com_SSL file in the same way as above:

# vi /var/cpanel/userdata/username/example.com_SSL

After your changes are complete save the file, and then delete the SSL_cache file for the domain:

# rm -vf /var/cpanel/userdata/username/example.com_SSL.cache

After that’s done, you need to rebuild Apache and restart the server using the following three commands:

# /scripts/updateuserdatacache

# /scripts/rebuildhttpdconf

# service httpd restart

You May Need to Change the Ownership of the Sub-Directory

One final change, I sometimes need to change the ownership of the 'web' folder. Permissions are set to 750, the same as the public_html folder, but I also change the ownership of the 'web' folder to nobody.

To make the change, you will need to be in the same directory as the 'web' folder, which is the 'public_html' directory for the account we're configuring. Execute the following command to go the 'public_html' directory:

# cd /home/username/public_html

Once you're in the 'public_html' directory you can change the ownership of the 'web' folder with the following command (remember to change 'username' to your cPanel account username):

# chown username.nobody web

That's it, the 'web' directory is now the documentroot instead of public_html.