Setting up a build server

There are a series of ways to set up a build server to work in conjunction with your Assembla Build Tool. If you don’t already have a build server running, consider using one of our predefined build servers that already have the Assembla Build Agent installed.

If you already have a build server, then you must install a Build Agent onto this server. The Build Agent is typically packaged as a CGI script executing under a web server on your build server. You can:

• Install one of our example Build Agents. These are example Ruby CGI scripts that you can customize to your needs.
  • Quick-start Subversion Agent. This highly streamlined agent simply performs a svn checkout/update.
  • Quick-start Git Agent. This highly streamlined agent simply performs a git clone/pull.
  • Basic Build Agent. This more complete agent supports all actions of our REST API.
• Install our Assembla Build Agent. This agent uses Capistrano to deploy, and permits limited customization.
• Write your own Build Agent from scratch using our REST API.

Installing an example Build Agent

This assumes that you already have a build server set up, including a web server. This also assumes that your build server already has all frameworks, packages, gems, eggs, etc. that are needed to successfully run your application.

1. Confirm your web server is working.
2. Install the following packages (if not yet installed): ruby (1.8)
3. Install packages for either subversion or git (corresponding to the Assembla repository type you’ll be deploying).
4. Download the scripts for the type of example Build Agent you want:
   • Quick-start Subversion Agent
   • Quick-start Git Agent
   • Basic Build Agent: configure action and deploy action
5. Copy the downloaded script(s) into your web server’s cgi-bin directory.
6. Change ownership of the downloaded scripts and home directory (to the user and group that your web server is running as):
   

   sudo chown <user name>:<group name> <script name>
   sudo chown <user name>:<group name> ~<web userid>

7. Change permissions so that the web server can execute your script:

   sudo chmod u+x <script name>

8. Configure your web server to run CGI scripts (if you haven’t already done so). For Apache:
   

   ScriptAlias /cgi-bin/ /path-to-your-cgibin-directory/cgi-bin/
   <Directory "/path-to-your-cgibin-directory/cgi-bin">
           AllowOverride None
           Options +ExecCGI
           Order allow,deny
           Allow from all
   </Directory>

9. Assembla will send deployment requests to your web server over port 44200. Make sure your web server is configured to receive these requests on port 44200.
10. Restart your web server. For Apache:
    

    sudo /etc/init.d/apache2 restart

11. Follow the appropriate setup steps below depending on which example Build Agent you are installing.

Setup the Quick-start Subversion Agent

1. Edit the script and insert values for these script variables:
   • CHECKOUT – add your Assembla login name and password
   • DEPLOY_DIR – the local directory where you want your application to be deployed to
   • UPDATE – add your Assembla login name and password
   • URL – the SVN Url that Assembla provides you to access your Subversion repository
2. Test that the CGI is available by opening a browser to URL: http://your-web-server-address:44200/cgi-bin/basic_svn.rb. You should see “Deploy agent is alive”
3. On your Assembla Build tab, set the Deploy action URL path to /cgi-bin/basic_svn.rb, and “Update settings”.
4. On your Assembla Build tab, set the Configure action URL path to /cgi-bin/basic_svn.rb, and “Configure build server”. You should see “Server configured, however it did not send an SSH key”.
5. Press “Deploy”. You should see “Deploy operation was queueued successfully”. There will be no Build Results posted, however if you look in the DEPLOY_DIR on the build server, you should see your repository deployed there.

Setup the Quick-start Git Agent

1. Edit the script and insert values for these script variables:
   • DEPLOY_DIR – the local directory where you want your application to be deployed to
   • URL – the public clone url that Assembla provides you to access your git repository
2. Test that the CGI is available by opening a browser to URL: http://your-web-server-address:44200/cgi-bin/basic_git.rb. You should see “Deploy agent is alive”
3. On your Assembla Build tab, set the Deploy action URL path to /cgi-bin/basic_git.rb, and “Update settings”.
4. On your Assembla Build tab, set the Configure action URL path on your Assembla Build tab to /cgi-bin/basic_git.rb, and “Configure build server”. You should see “Server configured, however it did not send an SSH key”.
5. Press “Deploy”. You should see “Deploy operation was queueued successfully”. There will be no Build Results posted, however if you look in the DEPLOY_DIR on the build server, you should see your repository deployed there.

Setup the Basic Build Agent

1. Install the following additional packages (if not yet installed): ruby1.8-dev, make, rdoc
2. Install Rubygems (if not yet installed) by following the Rubygems steps on this page.
3. Install json Ruby gem:
   

   sudo gem sources -a http://gemcutter.org
   sudo gem install json

4. Test that the CGI is available by opening a browser to these URLs:
   • http://your-web-server-address:44200/cgi-bin/basic_configure.rb. You should see “Configure agent is alive”
   • http://your-web-server-address:44200/cgi-bin/basic_deploy.rb. You should see “Deploy agent is alive”
5. On your Assembla Build tab, set the Deploy action URL path to /cgi-bin/basic_deploy.rb, and “Update settings”.
6. On your Assembla Build tab, set the Configure action URL path to /cgi-bin/basic_configure.rb, and “Configure build server”.
7. Press “Deploy”. You should see “Deploy operation was queueued successfully”. Refresh the page after a few minutes, and you should see Build Results.