Gábor Novoszádi – Interactive Media Designer

Install ProcessWire in a subfolder on shared hosting (cPanel)

install cPanel apache database

Last time I mentioned that I am going to install ProcessWire with the Regular Blog Site Profile named Uikit 3 site/blog profile. However, most part of this tutorial also applies to installing other site profiles, and better yet, the parts discussing "installing a website in their own subdirectories" is a general technique, not something that is restricted to ProcessWire sites, meaning you might find it useful no matter which CMS you are going to host from your account.

UPDATE on 01 April 2017: Due to a bug in the first beta versions of UIkit 3, the hamburger menu icon is missing in the current version of the Regular Blog Site Profile (7 Feb 2017). Below, I've added some additional instructions on how to fix it.

UPDATE on 24 April 2017: Important to note that the "Regular Blog Site Profile" showcased in this article should be considered to be a beta, prerelease version, which might need to be updated manually in the future.

Since my own CMS is served by a cPanel account, I wanted to install all the files for my Main Domain (also called primary domain) into a subdirectory so that if I later add other domains (either subdomains or Addon Domains) to the cPanel account, all the domain directories will be at the same level. I could not find any information on this particular setup, so I decided to write this guide.

I should mention that processwire.com is full of information on how to install the system. Also, if you get stuck the site provides a friendly forum to ask for help. But before you ask, please always read the docs first :)

Recommended readings/pages:

But what if I don't know how to code?

I borrowed these words of Joss Sanglier, I hope he does not mind. If you are a complete beginner and a bit worried to get started, you might want to read this page, where Joss raises some good arguments on why you should be ok in the first place :) Note that for the time being, it is enough to read the exact page I liked to.

Step by step in cPanel

Developers often have access to shared hosting environments running cPanel, so it makes sense to introduce the installation procedure this way.

For this tutorial I assume that you start out with the default cPanel files and settings. If not, do not forget to take into account any extra requirements your particular setup might need. I also assume that you want to install your very first ProcessWire site (in this guide referred to as example.com) in a way that it is served from the Main Domain your cPanel account is tied to.

Why in a subfolder? If you have a cPanel account it makes sense to separate all the websites hosted into their own folder so that they can be managed separately. Even if you only want to serve one site from your account, it can often be handy to clone your site to a subdomain (like dev.example.com) for testing purposes.

I do recommend that you install your very first ProcessWire site into a subfolder right at the beginning. It's always a good idea to stay organized rather then trying to tidy up later on, especially in software development!

Create subfolders first

NOTE: The theme of your cPanel account might be different from the one I use. You should be able to switch themes if you want to. The available themes are part of your account.

  • Log into your cPanel account, locate File Manager and open it.

  • Select public_html then click New Folder in the toolbar above.

  • Name this folder according to the domain your cPanel account is tied to (called Main Domain in the Stats sidebar), use this pattern: example_com

  • Create at least one more subfolder next to example_com, name it like: example_dev (this can be used as a testing site in the future, eg. running a copy of your site under the subdomain dev.exapmle.com).

This is a very basic setup, but you get the idea. If you want to host more sites, you just have to create a subfolder for each. Most shared hosting companies providing cPanel accounts also let their clients register and use more than one second-level domains (such as one-more-example.com and another-example.com). Second-level domains can be managed by cPanel's Addon Domain tool, where you can add more domains so that you can install other websites in subdirectories, as long as you have enough resources left for your account. This means you should not forget to check how many databases you are allowed to create, what storage is available to you, etc. Various restrictions can be applied to your account, most of then can be seen under Stats in the sidebar. Familiarize yourself with these.

The .htaccess file of public_html

Since cPanel/WHM accounts run Apache, in order to configure the webserver – to serve our primary website from a subfolder – we have to create/edit .htaccess files.

By default, your primary website running under your Main Domain is served from the public_html directory, but we want to change this behavior. This is how we can do it:

IMPORTANT: As a general rule, always make a backup of any files you modify, especially when you make changes to an already existing .htaccess file!

  • If you already has a .htaccess file in public_html then edit it. If not, create one.

    • To edit the file: click the file to highlight it, then click the Code Editor in the toolbar

    • To create one: click public_html to select it then click New File in the toolbar. Afterwards open it with the Code Editor button in the toolbar.

  • If you don't have a line in .htaccess which begins with RewriteEngine on then copy/paste the following code snippet to the bottom of your .htaccess file (if you alreday have this line, read on...):

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f 
RewriteCond %{REQUEST_FILENAME} !-d 
RewriteCond %{HTTP_HOST} ^(www.)?example\.com$ 
RewriteRule ^(.*)$ example_com/$1 
RewriteRule ^(/)?$ index.php [L]
  • Line 1: turns RewriteEngine on, which is used to allow for server-side manipulation of requested URLs.

  • Line 2 & 3: makes it possible to directly access files/directories that physically exist on the server. For example, if you upload something to /public_html/myfile.zip then it is possible to access and download it via http(s)://example.com/myfile.zip. Similarly, files in /public_html/mydownloads/ can be access via http(s)://example.com/mydownloads/myfile.zip and so on. If you do not need this sort of direct access, then you can just leave these two lines out.

  • Line 4, 5 and 6: line 4 is the condition that is used to decide whether the following rules must be interpreted or not. If the server request is about accessing your Main Domain either with or without www then the two rules will modify the URLs requested. The rule in line 5 injects the name of your subdirectory into the requested URL, while line 6 makes sure ProcessWire is run when the requested ULR is the start page of the site: /

  • So you pasted the code snippet into .htaccess; but do not save it just yet! Change the words example, com and example_com according to your domain name. When done, you can save the file.

  • Next create an index.php file in /public_html/example_com/ and copy/paste the following basic page into it (we do this is only for testing purposes):

<!DOCTYPE html>
<html>
<head><title>example.com</title></head>
<body>Works!</body>
</html>
  • If all goes well, when requesting your domain name in a browser the html page should show up, displaying "Works!" :) If not, something is not right with your .htaccess file in public_html.

IMPORTANT: If you already have the RewriteEngine on line then you have to analyze .htaccess before you make changes to it. Please proceed with care, because you might render your already running websites unreachable (if you have any). Do backup or make a copy of .htaccess first! (Eg. right click on the file, choose copy and read the onscreen instructions.) Copy/paste line 4, 5 and 6 to your clipboard. You can experiment to figure out where you need to paste them, but it must be somewhere after the line RewriteEngine on. If unsure, you can find various tutorials on the internet to learn more or you can ask in the ProcessWire Forums for help.

Your ProcessWire based website needs a database

Dealing with databases in cPanel is easy! If you do not already have a database, you have to create one. The recommended way to do it is with the MySQLDatabase Wizard. This way you can not only create a database easily, but a database user for it as well. For security reasons, I recommend that you always create and use a dedicated user for each database you have in your cPanel account.

Locate and click the MySQL Database Wizard icon.

  • Step 1: Create A Database appears. Give a name to your database which will be automatically prefixed by your username. It is important to note that the prefix will be part of the name! For example your database will be called like this: username_example_com

TIP: I recommend naming your databases like this: username_main_com, username_main_dev, username_addondomain_com, username_addondomain_dev etc. because this way they will be turned into a neat tree in phpMyAdmin. The important thing here is the usage of the underscore character between your domain name and the TLD. Also, the word "main" stands for your Main Domain, while you want to replace "addondomain" with your actual Addon Domain.

  • Step 2: Create Database Users appears. Users are also prefixed by your username which is also part of the name! You can name your database users similarly to your databases. I recommend names like these: username_user_com, username_user_dev, username_addo_com, username_addo_dev because this way you can tell them apart easily. Unfortunately cPanel only lets you add an 8 character long suffix when naming a database user. In my examples "user" stands for the user of the databases of your Main Domain while "addo" should be an abbreviation of your actual addon domain.

  • Step 3: Add a User to the Database appears. Click the checkbox ALL PRIVILEGES.

  • Step 4: Complete the Task appears. That's it! We can install ProcessWire in case you have jotted down your database name and password, which I hope you did ;)

ProcessWire's new Regular Blog Site Profile

It is high time you have your own blog as well :P Deploy the files we need:

  • Download the ZIP file of at least version 3.51 of ProcessWire from this page. You will get either processwire-master.zip or processwire-dev.zip depending on the version you chose. The file suffixed master is the current "stable" version, while dev is a version currently under development but normally just as stable as a master version meaning you can safely rely on it.

  • Download the Blog Profile from this page.

  • In cPanel, go to File Manager and browse to your /public_html/example_com directory. Click the Upload button in the toolbar. Click the Browse... button and find and open processwire-dev.zip on your storage device. The upload process begins.

  • If you have successfully uploaded the file, then click the ← Go Back to... link in order to get back to File Manager.

  • Select the uploaded processwire-dev.zip file and click Extract in the toolbar. The ZIP file will get extracted into the directory we want the website to be located.

  • Sadly, the extraction operation creates a subfolder named after the ZIP file's name – like processwire-dev – and this means we have to move all the extracted files and folders to their final destination.

  • Do this to move what you extracted:
    • Browse and open the processwire-dev directory.

    • Click Select All in the sub-toolbar.

    • Click Move in the toolbar, a pop-up window will appear.

    • Edit the path in the pop-up to point to /public_html/example_com/

    • Click the Move File(s) button.

    • Finally, remove both the empty processwire-dev directory and processwire-dev.zip by selecting them and clicking Delete in the toolbar.

  • So far so good. Now we could install ProcessWire by choosing one of the default site profiles it comes with. However, we want to install another profile, namely the not yet bundled Regular Blog Site Profile. This exercise is also good for showcasing how to install a "custom site profile" for ProcessWire.

    NOTE: There exists an officially supported Module called Site Profile Exporter to easily create your own distributable/installable site profiles. This is also the tool that is used to export all of the ProcessWire core site profiles. When you create an exported site profile, you can install it in the same fashion discussed below.

  • Upload the file regular-master.zip containing the Regular Blog Site Profile into the /public_html/example_com directory

  • Extract regular-master.zip into /public_html/example_com

  • Browse into /public_html/example_com/regular-master and select ONLY the folder called site-regular

  • Click the Move File(s) button to move the folder called site-regular into /public_html/example_com

  • Finally, it is time to delete the leftover directory regular-master and the leftover file regular-master.zip

After all this clicking-around steps, we are ready to run the ProcessWire installer!

Time to run the ProcessWire installer

In your browser go to your domain. If you have successfully completed all the steps so far, then the 5 minute ProcessWire installer appears.

NOTE: if you find hard to follow the instructions below, you can also read How to Install and Setup ProcessWire CMS by Ben Byford or watch this video by Zahari Majini (which is a bit old, but the process has not changed drastically).

  • Click the button Get Started.

  • The page titled Site Installation Profile appears, where you have to choose the site profile you want. From the drop down, select Regular UIkit3 site/blog profile.

  • Scroll down to the bottom of the page and click the button Continue.

  • The page with the Compatibility Check list appears.

  • You might get the message saying that the availability of mod_rewrite could not have been determined, but if you click the Check Again button, this message disappears, meaning you are ok to proceed.

  • Click the button Continue to Next Step.

  • Provide your database credentials (db_name, db_user, db_pass, and the rest can be left at default), adjust the time zone settings if needed, then click Continue.

  • Fill in the Admin Panel Information form according to you needs. I recommend not using the the word "admin" neither in the case of Admin Login URL, nor for the user. Pick something that is not commonly used. Leave the Cleanup section in its default state and click Continue.

    NOTE: passwords cannot be retrieved from the database, but you can reset them later on, should you forget... There are two different ways to reset passwords, neither of them is available in the default install of ProcessWire, so try not to loose you password in the fist place :) On the contrary, the Admin Login URL can be changed in the admin, meaning you can change your mind later on.

  • We've reached the last step where you get an overview of the completed installation process. There is a warning there asking you to change the permissions on the file /site/config.php You can follow the instructions provided if you want to, but nowadays cPanel accounts running in the same WHM virtual server are securely separated from each other, meaning you should be fine with the default 644 permissions.

Making a change to /site/config.php

Most ProcessWire site profiles use $page->url() in their template files, which provides a return value with the subdirectory the website is running from. However, this is not what we want in the case of our primary website we installed in /public_html/example_com, because we don't want ULRs like http://example.com/example_com/about to appear anywhere.

To stop the subdirectory being part of our URLs, $config->urls->root = '/'; must be added to /site/config.php

  • Open /public_html/example_com/site/config.php with the Code Editor found in the toolbar

  • Add $config->urls->root = '/'; to the bottom of config.php

That's all, you can login to your admin and visit your website which is preloaded with some placeholder stuff you will need to delete and/or edit. Editing the demo content is a good exercise to study the administration area of ProcessWire.

Making a change to /site/templates/_main.php

Due to a bug in the first beta versions of UIkit 3, the hamburger menu icon is missing in the current version of the Regular Blog Site Profile (7 Feb 2017). This is how you can fix it: In /site/templates/_main.php update https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.0-beta.9/css/uikit.min.css to point to .../3.0.0-beta.18/... that is beta 18 of UIkit 3. It is important to stick to beta 18 for the time being, as in UIkit beta 19 a breaking change was introduced: "Offcanvas requires to wrap page in extra div". In a similar manner, a JavaScript file must be added to the page: https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.0-beta.18/js/uikit-icons.min.js Add this after "uikit.min.js".

Troubleshooting tips if something went wrong

Have you already heard the secret that in reality WWW stands for Welcome to the Wild West, and not for World Wide Web? This means anything can go amiss. That is why I collected some links where you can find troubleshooting information:

And do not forget: you can always ask for help in the ProcessWire Forums.

Coming up next

In the next post I will explore the basics of the ProcessWire administration area and make some basic changes to the site profile to personalize it a little bit. I will also point out the importance of backups and provide some additional tips. Again, at this stage it will be basic information, specifically written for newcomers.

Credits: Special thanks to Robin Sallis for reviewing the draft version of this article!


Post a comment

Next A short introduction