Step-by-Step Tutorial

In the tutorial we assume that you're familiar with the following fundamental concepts of agile software development (well, actually, not only "agile"):

• You are familiar with continuous integration? Read Fowler's article and Humble's book.
• You keep your code under revision control? Start from wikipedia and Subversion manual.
• Do you understand the concept of "build automation"?
• Do you unit-test your code?
• You do static code analysis of your code?

If you just said "NO" to any of the above, start with the theory. You won't regret anyway.

Now you're ready since equipped. Four consecutive actions in a new FaZend account and your project starts a continuous delivery journey to its users (we assume that account creation is a simple task, and won't discuss it here):

1. Create a new project
2. Grant access rights to its participants
3. Configure CI settings
4. Monitor what's going on

Let's start from the first one.

Step 1. Create a new project

A project should have a unique name, containing letters and numbers. It should be less than 20 and more than 5 characters length. When you request a new project creation FaZend automatically does the following:

1. Creates Subversion repository
2. Creates and synchronizes a new Trac environment
3. Starts a backup cycle for SVN and Trac data

Normally all changes are completed in 5-10 minutes. The SVN repository and Trac URLs will be available in the FaZend account, when setup is done. Keep in mind that if you don't need a project any more you can delete it. The delete operation is irreversible, please be careful. Also keep in mind that you're allowed to have up to 3 projects in one account. If you need more you can archive unnecessary ones, and get more space for new.

Step 2. Grant access rights

When project is ready click "permissions" in the top left corner. Access rights to the project are managed with two Subversion access control files: authz and passwd. We assume that you understand how these files work, but if not please read the manual.

Provided your project name is SampleProj, there are three people in the team excluding yourself, one of them is an architect, one is a programmer and also one is a tester, this is how we would configure the authz file:

    [SampleProj:/]
    * =
    architect@example.com = rw
    programmer@example.com = r
    [SampleProj:/branches]
    programmer@example.com = rw

The second line with * =  means "no access to anyone", and the lines beneath it grant access to the selected people. There are no lines for the tester since he/she doesn't need any access to the Subversion repository, only to the Trac environment for bugs reporting.

We would configure the passwd file like this:

    [users]
    architect@example.com = kjf8KhfnmsP
    programmer@example.com = JJmf8Hns
    tester@example.com = jf6Hmn7J

Keep in mind that a password should be at least 5 symbols long. Also important to note that user name has to be an email. FaZend won't allow you to use names like "larry".

Step 3. Configure CI settings

Now you're ready to configure continuous integration. It's important to mention that by default your project is not under CI lifecycle, and you are limited to SVN+Trac environment (which is more than enough for some projects). If and when you are ready to start delivering your project to end-users continuously, email us at help@fazend.com. We will briefly review your requirements and turn ON this feature for you. Don't worry, it's just a formal interview. Know Your Client policy, you know :)

Click "CI settings" at the top of the page, and configure the project. If it is a typical Java build automated with Maven, we would configure it like this (it's YAML):

    SampleProj-java:
     source:
      scm: svn
      url: /trunk/java
     builder:
      tool: maven2
      goal: clean deploy site-deploy
      flags: -Pci --settings ../../closures/settings.xml
     closure:
      file: settings.xml
      content: |
       <?xml version="1.0" ?>
       <settings>
        <servers>
         <server>
          <id>deploy.example.com</id>
          <username>user</username>
          <password>secret</password>
         </server>
         <server>
          <id>site.example.com</id>
          <username>user</username>
          <password>secret</password>
         </server>
         <server>
          <id>repo.fazend.com</id>
          <username>you@example.com</username>
          <password>secret-fazend-password</password>
         </server>
        </servers>
       </settings>
     publish:
      JUnit Report: target/junit
     people: alex@example.com, peter@example.com
     notify: joe@example.com, viky@example.com
     monitor:
      url: http://www.example.com/my-page

The SampleProj-java is a unique name of the project in the shared continuous integration environment (shared by all other projects, not only yours and not only Java).

The url: /trunk/java is an instruction where to get your source code before its first automated build. The code will be checked out using your username and password (configured a few minutes ago as explained above). Currently we support Subversion (scm: svn), Git (scm: git), and Mercurial (scm: hg). You can get sources from some third-party repository, for example:

    SampleProj-fazend:
     source:
      scm: svn
      url: https://fazend.googlecode.com/svn/trunk
      username: my-name
      password: secret

Or from github.com, for example:

    SampleProj-fazend:
     source:
      scm: git
      url: https://github.com/fazend/somerepository.git

The tool: maven2 is a name of the builder. We currently support a limited amount of builders, but it's just a matter of installation of additional server software. Let us know if you need something specific, we will install. Of course we have Maven, Phing, Ant, and Make pre-installed.

The flags: -Pci --settings ../../closures/settings.xml is a string passed to Maven. The goal: clean deploy site-deploy is a list of Maven goals to be executed on every build cycle.

You can specify a number of build steps, for example:

    SampleProj-fazend:
     builders:
      Package and Deploy Artifacts:
       tool: maven2
       goal: clean deploy
      Deploy Site:
       tool: maven2
       goal: site:deploy --projects fazend
       flags: --settings ../../closures/config.xml

Closure is what we add to your workspace in CI environment before starting every build. It's a file where you keep your secrets, which should not be shared with anyone else in the project. As in the example, it's a settings.xml file, which is placed two levels up on top of the directory of your source code. You give a path to this file to Maven2 via a flag --settings ../../closures/settings.xml.

You can specify many closures, and even use binary files, pre-uploaded via fazend.com "CI settings" panel. The example below instructs FaZend CI server to place three files into ../../closures before starting a new build. build.properties's content is provided, while secring.gpg and pubring.gpg are expected to be uploaded through the panel (since no content provided herein):

    SampleProj-java:
     closures:
      build.properties: |
       ftp.home = ftp.my-site.com
      secring.gpg:
      pubring.gpg:

Using publish: option you can grab certain HTML artifacts from your project and publish them in your private Hundson environment. In the example we create a report named JUnit Report, getting its content from target/junit directory.

With people: you can grant read-access to the CI environment to anyone from your project. You can even make your Hudson page publicly accessible by anyone using people: * (be careful).

Using notify: you instruct the CI server to notify mentioned emails when build fails or returns back to normal state after failure.

By means of monitor: you ask our CI server to check your web system every few minutes and start a new build if the URL is not available or its status code is not 200. You can define as many monitors as you wish:

    SampleProj-java:
     monitors:
      front:
       url: http://www.example.com/abc
      backend:
       url: http://www.example.com/backend

Very soon we will install and configure Archiva, and you will get an access to your private repository of artifacts (as in the example, with repo.fazend.com).

You can configure a few builds for one project, but no more than five (if for some reason you need more, let us know, we will discuss). Every build is completely isolated from others.

Step 4. Monitor what's going on

Every few minutes all FaZend continuous integration, Subversion, and Trac servers review the status of your data, collect metrics, and publish them for your review, right in the account front page (click the logo to get there).

The list of metrics will be extended in the future. So far you can review how much resources your project consume on our servers. If you're interested in something else, let us know, we will add required metrics.

Feel free to email us if you need any assistance in your project setup, configuration, and maintenance.

---