Zend Server WebAPI spotlight: Continuous Integration

Hey everybody,

In this series of spotlight articles I will go over Web API actions that will be useful for implementing Continuous Integration. These Web API actions are those that provide feedback about execution and allow you to move and deploy your application to facilitate testing. Note that this article won’t tell you how to set up a CI system, as requirements and implementation vary wildly between companies and environments. Instead, we’ll tell you about tools that will make your life easier when looking for that perfect implementation.

Continuous Integration in a nutshell

Continuous Integration is the practice of automatically merging, building and testing an application. You can create endless variations on this definition but the same basic process recurs: merge all changes, build the application into a deployable form, deploy it and then run a battery of tests on it until it cries uncle. A consistent CI effort provides you with a safety net and the first line of defense against product defects and regressions.

CI lends itself well to agile development methodologies in its undying efforts to provide a “perpetually shippable product”. Let us remember that CI’s purpose, when all’s said and done, is to provide the entire team with feedback about their efforts of the day. It does not guarantee the application is actually any good and the system’s feedback is only as good as the developer that built it.

Note the above represents my own personal definition of CI. My personal viewpoint is skewed towards web application projects and therefore may not be a perfect fit for anything else.

Zend Server and the CI machine

Zend Server Web API provides a number of actions that can make your life easier. In this article I intend to discuss the applicationDeploy action. We will explore what this action does, how it is used and what benefits we gain from working in this particular way.

Application Deployment

Zend Server’s Deployment service provides a way to move packaged applications onto the server and there perform an automated installation process. The application files and associated hook scripts for execution are all packaged within a single zip file with the filename suffix “.zpk”. A deployment action on Zend Server accepts such a zpk file, unpacks it and moves the application files into a location on the filesystem. Once all files are in place, the webserver is modified so that an alias or virtual host is created to point at the application’s files and Zend Server is restarted.

Between these steps, Zend Server executes the hook scripts provided in the package to perform your custom activities for enabling your application. These can be anything from creating a stock database, generating a configuration cache or performing necessary steps for initializing the application.

When this process is complete, calling the application’s URL will have your application responding to requests and ready to run.

If you’d like more details about how a zpk is created and information about its advanced features you’re welcome to check Zend’s Youtube channel and the mass of webinars posted on this subject.

The packaged deployment process

ZPK package files are not only archives of files, they are the end result of a dev-ops promoting approach to version deployment. An important part of Continuous Integration is dealing with an application’s packaging and its installation. At its lowest, these steps are done manually by someone holding a piece of paper with instructions. I think we’ve all “been there” once or twice (or more) in our careers when changes to production explode into stunned faces and “but it worked on my machine” just doesn’t cut it.

Continuous Integration allows your application to go through the installation dozens, hundreds and thousands of times before production is ever approached. This allows you to meet any potential problems beforehand and solve them so that deployment becomes a breeze. CI introduces one difficult requirement to achieve this: automation.

ZPK files come to facilitate this requirement by providing you with a platform you can use to automate your deployment process. In effect, your deployment process turns into a part of your code – one which must be tested repeatedly and automatically. In your average CI cycle, the deployment of ZPKs will happen very often so that testing of that cycle may commence. The target for deployment may change but the package ZPK being deployed will always be the same.

Deployment, Web API style

Armed with the knowledge of ZPKs, how and why they are made, we finally reach the deployment action itself. The applicationDeploy action accepts a number of parameters which set the stage for the activation of your application on the webserver. This action is special in that it accepts a file upload, an unusual activity for a webservice.

The baseUrl parameter is used to determine the URL that will be used to access your application. This parameter must be unique within the system, though different baseUrls may overlap and be contained by others.

The defaultServer parameter is a flag to signal to the deployment process that the webserver should use the default vhost on the webserver to accept requests for the application. This flag will cause Deployment to replace whatever you entered as the host part of the baseUrl with a generic “all interfaces” string. This flag does not support vhost deployment and either allows you to deploy into the webserver formal root directory or use an alias (a path name) to access the application.

The userAppName parameter is optional and accepts a string with a descriptive name of the application. This parameter must also be unique across the system.

The userParams parameter is actually an array of values. To facilitate passing of parameters to deployment trigger scripts, userParams may be passed to the process. This is useful for passing passwords which should not be in the application files or can change per deployment. Note that these parameters may go through some form of validation – which may fail and require some kind of handling on the client’s side to try again.

Let’s see some code

$client = new ZendHttpClient();
$client->setUri('http://10.0.0.9:10081/ZendServer/Api/
          applicationDeploy')
 ->setEncType(ZendHttpClient::ENC_FORMDATA)
 ->setMethod('POST')
 ->setHeaders(array(
   ...
 ))
 ->getRequest()->getPost()->fromArray(
     array(
     'baseUrl' => 'http://mywebsite.com/',
     'userAppName' => 'my-web-site',
     'userParams' => array('myparam' => 'value',...)

 ))
 ->setFileUpload('/tmp/mywebsite.zpk', 'appPackage');

$response = $client->send(); echo $response->getBody();

After some time, this action should respond with:

  2
  http://mywebsite.com/
  mywebsite.com
  my-web-site
  /usr/local/zend/var/apps/...
  staging
  ...

Great, now what?

Deployment is one of those Web API actions that do not actually give you a “done” result. After applicationDeploy is called you actually have to wait for the deployment process to be completed. This usually takes less than a minute but YMMV as this time includes the execution of your trigger scripts.

Tracking deployment is similar to the methods described in previous posts. In most other cases we use the tasksComplete action to check on Zend Server’s activities. In this particular case we use the applicationGetStatus action instead. This way we get full details about the application in question and also its current state with regards to the deployment process. Note that you should pass the newly minted application’s id element value so that you get just your new application instead of a full list of all deployed applications.

Some more code

$client = new ZendHttpClient();
$client->setUri('http://10.0.0.9:10081/ZendServer/Api/
          applicationGetStatus')
 ->setMethod('GET')
 ->setHeaders(array(
   ...
 ))
 ->getRequest()->getQuery()->fromArray(
     array('applications' => array(2)))

 ->setFileUpload('/tmp/mywebsite.zpk', 'appPackage');

$response = $client->send(); echo $response->getBody();

The response should be immediate and familiar:

  2
  http://mywebsite.com/
  mywebsite.com
  my-web-site
  /usr/local/zend/var/apps/...
  activating
  ...

Once the status element has a value of “deployed”, the deployment process is complete and your application should be fully accessible from the internet. Should any errors occure, status will have an error value and the MessageList element will carry more human readable details.

Congratulations! If all went well, you should now have an accessible application which was automatically deployed and made ready to service your Continuous Integration efforts. You can now proceed to bombard your app with requests to your heart’s delight and hopefully, to major success.

Clusters and deployment

Clusters usually pose a challenge in a Continuous Integration environment. These servers have to be provisioned in parallel and require synchronization and advanced management. Deployment to these groups of servers can be tricky as some collaboration and coordination may be needed.

Fortunately, Zend Server Deployment handles all of this for you and an application you deploy onto a Zend Server cluster will automatically be made available on all servers. Note that you may still need to take care of your load balancer if you use something like that.

That’s it for today. Next time we look into what we can do with our Continuously Tested application and how Zend Server can help you identify problems and facilitate your tests.

Read more : Zend Server WebAPI spotlight: Continuous Integration