The Joomla! Community Magazine™

Building Joomla! Web-Help Systems - Part 2

Written by | Saturday, 01 March 2014 00:00 | Published in 2014 March
Installing Joomla in production environments - in this article I start with a basic, high-level explanation of how Apache's document root works, which I hope will give you a clear understanding of how you can easily install multiple instances of Joomla under a single domain. Next, I list some of the benefits of creating separate web-help sites for individual products. And, finally, I cover the options available for installing Joomla in your production environments.
Building Joomla! Web-Help Systems - Part 2 image by @Helvecio

Understanding how Apache's document root works

The Apache webserver has a root directory called the "document root." The document root is simply a directory on a server with content that is accessible to the Internet. On some Linux-based servers, Apache's default document root is often the html directory at the following path: /var/www/html. However, when using a commercial hosting provider, you will not be able to tell where Apache's document root resides on the server. You will be given access to the document root only. Your hosting provider will configure Apache to associate your domain name with the document root.

If your hosting provider supplies an automated Joomla installer, when running it you'll install Joomla in the document root. Otherwise, you'll upload Joomla to Apache's document root using an FTP client, or a control panel supplied by your provider, prior to installing it. When customers access your domain name on the Internet, Apache "serves-up" the contents of the document root, which is your website, to their browsers.

When you only need a single Joomla website, you can install Joomla directly in Apache's document root. However, if you want to create a system like mine, with separate Joomla web-help sites for individual products, then you can install separate instances of Joomla, one for each product, in sub-directories in the document root. Note that you can create countless sub-directories in the document root, and you can create many databases in the MySQL server; therefore, you can install as many instances of Joomla under your domain as required (assuming this is allowed by your hosting provider).

For example, if I were creating web-help sites for two products, one named AppA and the other AppB, I would upload and install two full instances of Joomla in separate subdirectories in Apache's document root:

document-root/AppA

The AppA directory would contain an entire Joomla instance for the AppA web-help site, accessible at http://my.domain.com/AppA

document-root/AppB

The AppB directory would contain another Joomla instance for the AppB web-help site, accessible at http://my.domain.com/AppB

After setting up the AppA web-help site, I would give the URL (http://my.domain.com/AppA) to the AppA developers. They would associate the URL with the AppA Help button and configure it to open a browser window when clicked. Likewise, I would give the URL for the AppB web-help site (http://my.domain.com/AppB) to the AppB developers, who would do the same. After purchasing and installing either the AppA or AppB products, customers could click the Help buttons in their applications to view the product documentation on the appropriate Joomla web-help site. In addition, customers could access the documentation outside of their products by going straight to the URLs for each product documentation site.

Creating separate web-help sites

In the following sections I describe some of the benefits of creating separate Joomla web-help sites for individual products.

Supporting usability

If the products you document include a substantial amount of functionality, you probably write numerous help topics for them in your current help systems. Since you wouldn't document multiple products in a single, product-specific help system, you also shouldn't document multiple products on a single Joomla web-help site. For instance, some of my Joomla web-help sites include hundreds of help articles, all of which are chunked into two or more pages (sometimes up to twenty) with page breaks. Combining the documentation for two or more of these products on a single Joomla web-help site would result in a site that was hard to use.

Securing content

Your company may decide the documentation for one or more products should not be publically accessible on the Internet. When you deploy separate Joomla web-help sites, you can "hide" content with various permissions and use different authentication solutions for each site. For example, Joomla has a built-in LDAP authentication module, which would enable you to authenticate users against LDAP systems. You can also find authentication plugins on the Joomla extension portal. You could develop a solution in which clicking an application's Help button passes credentials to a Joomla authentication plugin, which would automatically sign users into a Joomla web-help site. In this scenario, your content is secure and customers don't have to memorize yet another password.

Customizing layout and appearance

Our products are styled with corporate colors and logos to provide customers with a consistent branding experience. I customized an open-source Joomla template to match to our corporate style guide and install it on every web-help site. However, if our products all had different color schemes, I could customize the template to match each product. With separate web-help sites you can, if required, install different templates with unique layouts and capabilities.

Planning for multiple Joomla web-help sites

If this approach sounds interesting, I don't expect you to install multiple instances of Joomla for different products under your new domain immediately. But, if you think you might implement this kind of setup at some point in the future, be sure to select a hosting provider that supports this type of configuration. While I believe this setup is common, it is something to keep in mind when researching providers.

Installing Joomla in your production environments

This article would become much longer if I were to include step-by-step instructions on installing Joomla. However I don't have to document the installation process, because it's already documented on the Joomla documentation portal. In the following sections, I cover the options for installing Joomla on hosted systems and corporate servers, and provide links to the supporting documentation on the portal.

Installing Joomla on hosted systems

If you choose a hosting provider that specializes in Joomla sites, they will provide an auto-installer, which you can use to install Joomla in a few clicks. In this case, you should follow your hosting provider's installation instructions.

Note: To learn about the two most-common auto-installers, see Installing Joomla using an Auto Installer on the Joomla documentation portal.

If your company already has a hosting provider, or you choose a provider that doesn't specialize in hosting Joomla sites, the installation process will consist of more tasks and steps; however, none of them require a great deal of technical proficiency. For example, you'll need to upload the Joomla software to the web server's document root via an FTP client before stepping through the installation process. To learn how to install Joomla with a hosting provider that does not specialize in Joomla sites, see Installing Joomla version 3.2 on the Joomla documentation portal.

Installing Joomla on your own servers

If you plan on installing Joomla on your own servers, you or your IT department should prepare the servers ahead of time. The process of setting up production servers includes more steps than I can list in this section. But, assuming your servers are set up properly, here is a list of tasks that will help you prepare for installing Joomla:

  • Install the supported versions of Apache, PHP, and MySQL. For reference, see the Technical Requirements page on the documentation portal.
  • Ensure that your server's IP address is associated with a domain name and that your domain name is added to Apache's ServerName parameter.
  • Create an administrative user account with all privileges in MySQL. You'll need the username and password for this account when installing Joomla.
  • Create an empty database in the MySQL server for each Joomla web-help site. You'll supply a database name when installing Joomla.
  • Increase the upload_max_filesize parameter in the php.ini file to at least 8 MB, which is set to 2 MB by default. Many Joomla extensions and templates are larger than 2 MB - some by a good margin. If you don't increase the file upload size, the process of installing extensions and upgrades larger than 2 MB with Joomla's Extension Manager will fail.

In addition, you'll need a user account on the server itself with access to Apache's document root. And, you'll need an FTP client for uploading Joomla to the server.

When your servers are properly configured, you can install Joomla. Follow the instructions in the Installing Joomla version 3.2 article on the Joomla documentation portal.

About Part 3

In Part 3, I'll cover options for installing Joomla on learning and development environments.

Read 8002 times
Tagged under Sitebuilders, English