The Joomla! Community Magazine™

Automating Your Component Demo Site

Written by | Saturday, 01 December 2012 00:00 | Published in 2012 December
These days almost all Joomla! developers have a demo site to display their component for testing. It really doesn’t matter if you give your component away or if you are offering it for purchase; most users expect to be able to test the functionality and “see it in action” before they purchase or waste their time downloading and installing on their own site. This means as a component developer you have to keep a demo site up and running at all times with the latest version of your component.

There are several different ways to accomplish this. I’d like to present the way our shop at www.crmery.com has found to be most successful for us. I don’t imply this to be the only way to run a demo site (or even the best way – we seem to be always tweaking things), but this has proven to be extremely efficient for our purposes. I thought it may be helpful to others as well.

We use GitHub for managing our software versions and as a result we have some very powerful tools that we can take advantage of to make our demo site always stay in sync. You can configure your repository in a variety of ways and in another post I will go into detail about how Joomla! handles their repositories and how we have chosen to handle ours. The bottom line is that you need to have a master or production branch. This branch only contains stable code. You should be able to download your code from this branch and it will install and run without any problems. This is the branch we want to reference for our demo site.

GitHub provides hooks to a variety of applications and functions. You can find these by going to the admin section of your repository. Once in the admin side you will find the “Service Hooks” on the left hand menu as referenced in the image below.



Clicking on the Service Hooks will give you a list of available services you can reference. GitHub hooks provide a convenient way to receive information about each commit as it’s made on your repository. Any hook you define will be triggered every time you commit to your repo. Don’t be overwhelmed. We are only going to look at one, the very first option, Web Hook URL’s.  What we are going to do is enter a path to a location on our server where we have a special git folder. You will need to enter the URL in the standard browser accessible format:

e.g. http://demo.crmery.com/gitrepo/git.php

Save your changes and you’re done for the moment on GitHub. We’ll revisit this later to test the service hook and add our SSH keys. Now you need to go setup this special git folder on your server. This will involve a couple of steps. The first thing you should probably do is make sure that git is enabled and running on your server. You can do this by opening up a terminal window and simply typing

git --version

You should see a result similar to the following:

git version 1.8.0

If you get a command not found error then you will need to setup git prior to continuing.  Once you know git is installed on your server you’re ready to move to the next step. You will need to create the directory and file which you entered at GitHub. In our case we need to create a folder called gitrepo and then add a file named git.php.

For the contents of the git.php file we add the following:

<?php
if($_REQUEST['payload']) {        shell_exec('/usr/local/bin/git fetch --all &&
        /usr/local/bin/git reset --hard origin/master');
}
?>

This is the file and code that will be run each time your GitHub hook is triggered. GitHub will deliver a set of post variables, namely one called payload. This contains the details of the commit. If you have a valid payload then this file runs a git command to interpret the payload.

Before you test your hook and script there are a few more things we need to set-up. Don’t give up, we’re almost there.

Your GitHub requires authentication before making any pulls remotely so you need to configure your GitHub and your server to authenticate silently and automatically using SSH keys. GitHub has a wonderful article on configuring your SSH keys so I don’t have to go into detail about that process, suffice to say, it’s simple to follow their steps.

*One thing to note here – be sure that the user you use to create your id_rsa key is the same user that will run your git command in your git.php file above! In most cases this is the apache user. This is critical for authentication.

After you have configured your SSH keys you will need to test this by running a git command as this user and make sure your connection to GitHub authenticates and works correctly. Since we need a starting copy of the repository to begin with anyway we can test our authentication at the same time. Navigate into your gitrepo folder you’ve created previously and run the following commands:

git -clone This email address is being protected from spambots. You need JavaScript enabled to view it./your_repo_path/repo.git
git -fetch --all origin/master

You should see a connection established to github and a clone of your repository begin. You have now copied all the files from your repository into your gitrepo folder. Congratulations! Your git settings and your SSH keys are working correctly. Now you can test your GitHub hook by posting a commit to your repository and checking the files in your gitrepo folder on your server. You should see your changes almost instantaneously. If you do then you have only one small step remaining and your automatic demo site updating will be configured.  If you do not then you will need to step back and see at what point the process is failing. You can always use the GitHub guides to answer any specific questions.

The last step to setting up your automated component demo is to make sure that your Joomla! site uses those files located in your gitrepo folder. The easiest way to accomplish this is to set a few symlinks. By setting symlinks you can keep your directory structure of your github repository the same within your gitrepo folder on your server. In case you need an example, here is one way that might look:

/gitrepo/
git.php
manifest.xml
/package/
/component_folder/
install.php
component.xml
/admin/
/site/

Simply create a symlink in the Joomla! component folder on the front side to the site folder within the above structure.

ln -sv /home/yourpath/public_html/components/com_component 
/home/yourpath/public_html/gitrepo/package/component_folder/site

Create a second symlink for your admin folder on the administrator side of Joomla! and you are done.  Now every time you push a new version to your master branch of your GitHub repository you will automatically update your demo site with the newest code.

There is one little matter of the database that needs to be configured but you can handle the updating of that by simply running your install.php script as part of your git.php file.

Leave a comment if you’d like to see a follow-up post describing these steps and how to keep your databases always in sync through GitHub as well.

I hope this article has helped you see one way in which you can reduce your workload by updating your component demo site automatically. Obviously the same methodology holds true for modules and plugins as well. Be sure to watch for my next article on how to simplify your deployment procedures from your desktop to your member’s only file repository.

Read 57227 times
Tagged under Developers, English
David Hurley

David Hurley

David Hurley is an open source advocate and travels most weeks of the year to speak around the world on topics of tech, PHP and open source software. He is the Community Manager for Joomla - the second largest content management system in the world. He is also a member of the Production Leadership Team and the Framework maintainers. David writes semi-obsessively at http://dbhurley.com and is an active partner in several businesses.