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.

 Practical Development

Upon completion you should be able to create a development setup with with one or more parallel installations of XAMP, 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 tooling we employ ) to find its 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 tooling

##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 i would advised to use the latest version, but in combination with Joomla! (or any platform with specific requirements) you might want to pick a specific Apache, MySQL and or PHP version into consideration and install versions in parallel.

For example, 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 php54 (my default) and a version with last PHP 5.3 version to use with Joomla! 1.5 issues. But you could 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 examples 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 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 obviously 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 webiste names by adding them to the hosts file. Now the browser can use the sites name to connect.

On Linux machines, the hosts file can be found at /etc/hosts, on windows machines its 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) and use it throughout as basis for naming. I discard of any www, for the base naming and on localhost i prepend local. , a shared external development site would be pre-pended with dev. Using this naming convention also helps when using tooling 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##. Production site viryagroup.com would have a local counterpart local.viryagroup.com ( local.##DOMAIN## ), 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 hosters providers provide 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 cusomer. When experimenting be sure to initially set the time to live (TTL) for the records to low value to ensure your changes are propagated quickely.

Configuring Apache

Now we have the naming and name lookup taken care of we still need to tell the web-server, Apache in XAMP, 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 "xamp" applications through a vhost named "xampp", where 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 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 example 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 done 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 your hearts desire, 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-availble) 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, 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 later section on linking)

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 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 an 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. Not 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 example ##PROJECTS##/[apps] directory to keep it in the projects directory.

To avoid duplication with multiple XAMPP installations, the 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 system, 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 example for automation tasks.