The Joomla! Community Magazine™

Practical Development 2: Working Environment

Written by | Saturday, 01 March 2014 00:00 | Published in 2014 March
The second in a series of articles on practical development, dealing with your working environment in developing for Joomla! Consult last month's introduction for what to expect.

Setting up your working environment and tools

vg swdev 0000 setupDefine a (directory) structure, with "project directories" that allows for multiple projects / sites in your workflow. A project directory will be the central location for all data related to a project, making it easy to archive projects or transfer to a different system.

Make use of (soft-)linking (also on windows!) of files and directories, making files from outside the "project directory" available within that "project directory". A link basically provides multiple locations to access the same file.

Upon completion you should be able to create a development setup with with one or more parallel installations of XAMPP, and multiple independent projects. Each project will be accessibly locally via its unique name in the browser.

We will need to:

  • setup the projects directory (folder folder structure),
  • install XAMPP to have a server stack with Apache, PHP and MySQL
  • configure the system and Apache webserver for virtual and name based hosting (vhost)
  • tweak our configuration using "links"

Projects directory

The organisation of our projects revolves around the projects directory to manage the project directories. A defined structure allows us to keep all of our project data in "one" place with naming conventions which make it easy for us ( AND any tools we employ ) to find their way. By using relative references, we can be agnostic of the OS platform used ( Windows, Linux, Mac ). In this way you can move your project between systems and archive it by moving the project base directory with all relevant data in it.

To describe the projects directory structure we will be using naming conventions. Any names between ## are variables you may use – they are to be "replaced" with what ever is your preference.

The proposed basic set-up looks like:

##PROJECTS##/[apps]
            /[archive]
            /local.##DOMAIN##/www
            |                /logs
            |                /backup
            |                /patches
            /local.##DOMAIN##/www
                             /logs
                             /backup

And for the XAMPP tools

##XAMPP_INSTALL##/apache/conf
/php
/mysql

##XAMPP_INSTALL## would be the installation directory for XAMPP
##PROJECTS## is the base or root for the projects directory structure used to store the all of your projects.

I set up "d:/virtualhosts/" as my projects directory as you will see throughout.
##DOMAIN## is the domain name for the respective projects (explained in more detail later), then we have project base directories named as ##PROJECTS##/local.##DOMAIN##

We will be expanding on this structure in this article series and add detail as we go. In the end you should be able to build a structure that fills your needs.

XAMPP

XAMPP, is one of the options available to run a local web server, MySQL and PHP stack on you windows ( or other platform ). Its basic operation and install are covered extensively throughout the net and not covered here.

XAMPP Parallel installations

Typically it is advised to use the latest version, but If you are working with Joomla! (or any platform with specific requirements) you might want to specify the version you use. It is possible to run different XAMPP versions in parallel. Select your XAMPP versions with specific Apache, MySQL and or PHP versions that are of interest to you and install these in parallel.

For eXAMPPle, when looking at PHP as a the variable you could  consider:

1.7.7   last XAMPP version with php 5.3    (5.3.8)
1.8.2-1 last XAMPP version with php 5.4.x  (5.4.16)
1.8.3-0 first XAMPP version with php 5.5   (5.5.1)

You can/could install any combination in parallel, but typically have only one active!

In my current set-up I have two installs, one with PHP 5.4 (my default) and a version with last PHP 5.3 version to use with Joomla! 1.5 issues. You could, however, also consider PHP 5.5 for some bleeding edge testing.

XAMPP Installation locations

You are free to install XAMPP anywhere, as long as you know where. For the above eXAMPPles of php 5.4 and php 5.3 I have them installed at respectively:

C:\Portable\XAMPP
C:\Portable\XAMPP-php53

For the sake of later reference, the Installation / unpack Location C:\Portable\XAMPP or C:\Portable\XAMPP-php53 shall be referenced to as ##XAMPP_INSTALL##

Setting up name based hosting

We will want to be able to work on multiple development sites / set-ups in parallel. So each development site will run on/in its own virtual host, and "behave" as a real site with its own site name (domain name). This is not only a clean approach, its necessary when we come to debugging later in this series. 

To achieve this we need to set up name based hosting and we need to set up a so called hosts file, a virtual host configuration for Apache, and finally the vhosts configurations files for each of your projects.

hosts file

Think of a hosts file using the analogy of a telephone, when your browser needs to connect to a website, it has to look up the sites telephone number through its name in a telephone directory. Locally and for test purposes your local hosts file acts as that telephone directory.

A server running on your own computer is typically accessible via the IP-address 127.0.0.1. We can now link that ip-address to several different website names by adding them to the hosts file. Now the browser can use the site's name to connect, for eXAMPPle by entering http://local.viryagroup.com in the address bar.

On Linux machines, the hosts file can be found at /etc/hosts.  On windows machines it is more hidden. See Hosts wikipedia entry for more details on the location of the hosts file per OS. Personally I use a simple utility called windows hosts file editor which needs to be run with/as administrator to be able to save the hosts file.

Site naming, adding entries to hosts file

Using some kind of naming convention for your development sites, preferably related to the production site, will make your life easier in the long run. As a convention I sugguest to take the domain name of the site under construction (production site), without the www. and use it throughout as a basis for naming.

Websites running on your local computer will have their name begin with local. (local.viryagroup.com) and a shared, external development site would have a name starting with dev. (dev.viryagroup.com). Using this naming convention also helps when using tools for remembering passwords such as keepass or lastpass.

We will refer to the domain name of your production site as ##DOMAIN## and the local or dev designation as ##SUB##.

As an example production site viryagroup.com would have a local counterpart local.viryagroup.com ( local.##DOMAIN## ) and the entries for the host file would be:

127.0.0.1  local.viryagroup.com
127.0.0.1  www.local.viryagroup.com

For shared collaborative development we would choose dev.viryagroup.com ( dev.##DOMAIN## ). This site would would be hosted on a external ( as in not on you own computer ) server. In order to access the "dev" server" you either add it to your local hosts file, or more preferably, add it to the DNS of DOMAIN by adding A records similar to the hosts file entries to the zone_file. Apart from editing the zone file there is not one single way of doing it, but most hosting providers offer cPanel or some other web-interface to easily add A records. Having the "dev" site set up in the DNS allows for easy sharing progress with the customer. When experimenting be sure to initially set the time to live (TTL) for the records to a low value to ensure your changes are propagated quickly.

Configuring Apache

Now we have the naming and name lookup taken care of, we still need to tell the web-server, Apache in XAMPP, how we want that site to be handled and where to find the content. The location

##XAMPP_INSTALL##/apache/conf

will hold the configuration files used by Apache. The files to be modified are extra/httpd-vhosts.conf and httpd.conf.

extra/httpd-vhosts.conf

##XAMPP_INSTALL##/apache/conf/extra/httpd-vhosts.conf

First we need to enable "name based virtual hosts" in the Apache web-server (XAMPP). Un-comment (remove any leading "#") from the line
##NameVirtualHost *:80

NameVirtualHost *:80

Thas all there is to it, to have access to the original "XAMPP" applications through a vhost named "XAMPP", where the document root would be "##XAMPP_INSTALL##/htdocs". Optionally add the following to the end of httpd-vhosts.conf (replacing ##XAMPP_INSTALL## with your location):

<VirtualHost *:80>
    ServerName XAMPP
    DocumentRoot     "##XAMPP_INSTALL##/htdocs"
</VirtualHost>

defining vhosts : sites-available sites-enabled

Next we are going to create the actual vhosts for use in the web-server, where each vhost file defines the specific configuration for that website. Now we could have added all of our vhosts configuration to httpd-vhosts.conf, but we are taking a more structure-based approach (as used in "debian"). We will create individual ##DOMAIN##.conf files for the respective websites (vhosts / domains).

These configuration files will be stored and controlled from the folders sites-available an sites-enabled.

sites-available
##XAMPP_INSTALL##/apache/conf/sites-available

The sites-available directory will hold all of the ##DOMAIN##.conf files we could be working on, and that directory needs to be created. Note that actual activation of the vhosts comes later.

As set out in the working strucuture section, we want to organise all our vhosts in one location named ##PROJECTS##. So for a single site we would have:

##PROJECTS##/##SUB##.##DOMAIN##

as a basis. As an eXAMPPle we could have:

D:\VirtualHost\local.viryagroup.com\www
| \logs
\local.joomla3\www
\logs

Now the vhost.conf files that we need to create for each project needs to reference the working directories:

<VirtualHost *:80>
    ServerName ##SUB##.##DOMAIN##
    ServerAlias www.##SUB##.##DOMAIN##
    DocumentRoot     "##PROJECTS##/##SUB##.##DOMAIN##/www"
    ErrorLog         "##PROJECTS##/##SUB##.##DOMAIN##/logs/error.log"
    CustomLog        "##PROJECTS##/##SUB##.##DOMAIN##/logs/access.log" combined
    <Directory       "##PROJECTS##/##SUB##.##DOMAIN##/www">
        Options Indexes FollowSymLinks Includes ExecCGI
        AllowOverride All
#        Order allow,deny
#        Allow from all
        Require all granted        
    </Directory>
</VirtualHost>

In this setup the www and the logs directories are mandatory. You need to create them as sub directories to the ##PROJECTS##/##DOMAIN##. Failure to do so will result in XAMPP not starting.

When this is completed a vhost.conf file would/could look like:

<VirtualHost *:80>
    ServerName local.viryagroup.com
    ServerAlias www.local.viryagroup.com
    DocumentRoot     "D:\VirtualHost\local.viryagroup.com\www"
    ErrorLog         "D:\VirtualHost\local.viryagroup.com\logs\error.log"
    CustomLog        "D:\VirtualHost\local.viryagroup.com\logs\access.log" combined
    <Directory       "D:\VirtualHost\local.viryagroup.com\www">
        Options Indexes FollowSymLinks Includes ExecCGI
        AllowOverride All
        Require all granted        
    </Directory>
</VirtualHost>

You can tailor any vhost.conf to meet your own needs. The number of options is endless but this is not within the scope of these articles.

sites-enabled
##XAMPP_INSTALL##/apache/conf/sites-enabled

Now we know (from sites-available) what vhosts we could work on and how they are set-up, we are going to define what we actually are working on. The sites-enabled directory holds a selection of the files from sites-available, for the vhosts actually in use.

Either copy the relevant vhost.conf files into this directory, or more preferably, create a soft link from the "sites-available" location. 

In Debian this is managed by the a2ensite and a2dissite commands. In Windows we need to that by hand or mouse (see the section below on linking).

After a site is enabled, be sure to restart your apache webserver using the XAMPP control panel. When not using XAMPP, consult your documentation on how to do this. 

httpd.conf

##XAMPP_INSTALL##/apache/conf/httpd.conf

With all the vhost.conf files in the sites-enabled location, we still need to tell Apache about it, so they will get used. To achieve this you have to modify the httpd.conf file. Find the section:

# Virtual hosts
Include "conf/extra/httpd-vhosts.conf"

and add the line:

Include "conf/sites-enabled/*"

Linking

The (soft) linking of files and directories is a known concept in Linux. Oversimplified linking allows referencing a single file / folder from multiple locations. Using linking you can access files and directories from more logical and easy-to-remember locations, and avoid duplication of data. 

Contrary to common belief, linking is also available as native in recent windows versions via the mklink.exe command. Forms of linking include:

Softllink, transparent reference to another file, through to the "filename"
Hardlink, reference to another file ( refencing its content )
Junctions, is to folders what a softlink is to a file

For a more in depth discussion see http://schinagl.priv.at/nt/hardlinkshellext/hardlinkshellext.html. Here you can download hardlinkshellext which is a tool that allows for easy creation of all kinds of links using 'explorer'.

Unfortunately not all applications are aware and prepared to handle links. In this series of articles we will be using links where possible to make life more easy. Note that restrictions may apply due to the level of support from the relevant tools.

XAMPP related link trickery

To keep an even tidier organization we can move the "sites-enabled" and "sites-available" into for eXAMPPle ##PROJECTS##/[apps] directory to keep it in the projects directory.

To avoid duplication with multiple XAMPP installations, there may need to be in a directory reflecting the XAMPP version. Like ##PROJECTS##/[apps]/xampp173/sites-enabled:

##PROJECTS##/[apps]/xampp177/sites-available
| /sites-enabled
/xampp183/sites-available
/sites-enabled

Once done on Windows, a junction can be used to "link" the sites-enabled directory back into the XAMPP context.

##PROJECTS##/[apps]/xampp177/sites-available
/sites-enabled =J> ##XAMPP_INSTALL##/apache/conf/sites-enabled

Note that in this setup (using junctions) under Windows, you need to copy vhost.conf files from ##PROJECTS##/[apps]/xampp177/sites-available to ##PROJECTS##/[apps]/xampp177/sites-enabled. Unfortunately soft linking does not work in junctions. We will adress this when we come to the building article.

When done we are left with those vhost.conf in locations that are then more readily "available for eXAMPPle for automation tasks.

 

Read 12109 times
Tagged under Developers, English
Marco Dings

Marco Dings

Marco is a long-time technology professional based in the Netherlands, who cut his teeth in the early 90's writing his own Content Management System for his employer, eventually being fast-tracked into a management position where he was responsible for embedded systems - the software which runs our TVs, video games consoles and phones to name but a few.

After starting his own business in software and cosultancey, Marco decided to focus on webdevelopment using Joomla. Now fasttracking the business as co-owner, and CTO of the Viryagroup (merging Virya Technologies & Blox42).