DITA Open Platform
msgbartop
The Open Source DITA Authoring Platform
msgbarbottom

30 Dec 08 Getting started with EasyTrac


Running the server

  1. Open a Windows command line and go to the C:dita-op folder.
  2. Enter the run command.
  3. To stop the server you will have to type the Ctrl-C key combination.
You can now verify your installation.


Verifying your installation

Once the server is started it is available on port 8181, it comes with a pre-configured project named “example” that enables you to test the installation and see how things are working.

The following steps will enable you to verify that all the components are properly working.


Subversion and the Trac server

  • Open your favorite Internet browser and go to http://localhost:8181. If you get a page with “It works!” written on it, the HTTP server is properly working.
  • Go to http://localhost:8181/svn/example/trunk/. You should get a page titled “Revision 3: /trunk” which lists the sources for the DITA Architectural Specification and Language Reference that are used in the “example” project. This indicates the Subversion installation is properly working.
  • Go to http://localhost:8181/projects/example. This is the Trac project page for the “example” project. From there you can create wiki pages and browse the project sources using the Trac source browser (more information on The Trac User and Administration Guide)


The continuous integration build

The DITA-OP EasyTrac package is coming with the Bitten Trac plugin installed and everything necessary to launch build configurations produced by the DITA-OP Editor.

The installation already contains the result of a successful build, the output of this build is available at http://localhost:8181/builds/build_ditadoc_1/ but, since Bitten will not build the documentation again if nothing has changed in Subversion, we have to invalidate this build before launching the Bitten slave that will re-build the documentation.

  1. Invalidate the build result.
    1. Click on the login link in the upper-right corner of the project page. The browser asks you for your username and password
    2. Enter admin as username and password and validate.
    3. Click on the Build Status button in the menu bar. This page displays the results of the continuous integration builds. The one we need to invalidate should be listed here, in a green box.
    4. Click on the title of the green box. You are directed to the details page of this particular build.
    5. Click on the Invalidate build button. No build result should be listed anymore.
  2. Open a Windows command line and go to the C:dita-op folder.
  3. Enter the slave example command. The console output should log that the slave is contacting the Trac server then checkout the files from Subversion and launch the DITA Open Toolkit builds.
  4. You can check the progress of the build on the Build Status page.


Configuring the server

There is not much room for configuration, however, in order for the server to be accessible from other computers, the server must be given a public name.
  1. Using your favorite text editor, open the C:dita-opsetenv.cmd file.
  2. Locate the line set DOP_HOST=localhost and replace localhost with the public name of your server.
  3. Optional: You can also change the port the server is using. In the C:dita-opsetenv.cmd file locate the line set DOP_PORT=8181 and replace the port 8181 with the port number of your liking.
  4. Restart the server.


Creating a Trac project

Besides the “example” project that comes with the EasyTrac package you will need to create your own projects to manage your documentation.
  1. Open a Windows command line and go to the C:dita-op folder.
  2. Type the addproject projname command where projname is the name of the project you want to create.
Once the new project is created, the associated Subversion repository is accessible at http://localhost:8181/svn/projname and the Trac project is accessible at http://localhost:8181/projects/projname


Adding users

The Subversion repositories and Trac projects are anonymously accessible in read-only mode. To be able to write into the repositories, edit wiki pages or work Trac tickets, users must be added and given access rights.

By default the DITA-OP EasyTrac package comes with only one administrative user whose user name is “admin” and password is “admin”.

  1. Open a Windows command line and go to the C:dita-op folder.
  2. Type the adduser username command where username is the name of the user you want to create. The system will ask you twice for the user’s password.
  3. Go to the Trac project page and login as admin.
  4. Optional: By default any authenticated user will have the necessary rights to use the wiki and work Trac tickets, however, follow those steps if you want to give them additional rights.
    1. Click on the Admin menu
    2. Select the Permission menu on the left-hand side bar and then add permissions as necessary. See the Trac Permissions page for more information.


Creating a build recipe

In order to enable continuous building of your documentation you need to configure a Bitten build recipe. The “example” project contains one recipe that you can use as an example. Once logged in as an administrator you can see it here: http://localhost:8181/projects/example/admin/bitten/configs
  1. First you need to create a DITA-OT launch configuration and commit it in Subversion.

    There is one limitation though, references to files cannot be absolute, they must be relative to the Eclipse workspace. You must use the ${resource_loc} variable to reference files in the workspace.

    The “example” Subversion repository contains two Eclipse projects, archspec and langref, that both contain an example of launch configuration suitable for continuous integration.

    You can check them out in Eclipse from the following Subversion repository URL: http://localhost:8181/svn/example/trunk/

  2. Go to your Trac project page and login as administrator.
  3. Open the Admin panel and select the Builds > Configurations section.
  4. In the Add Configuration panel on the right of the page enter a name, a label and the relative path of the Eclipse workspace in the Subversion repository (if you follow standard conventions, this should be trunk )
  5. Press the Add button.
  6. In the recipe textarea enter the XML build recipe. See Bitten Build Recipes for more information on build recipes. Following is an example: 
    <build xmlns:dop="http://dita-op.org/tools" xmlns:svn="http://bitten.cmlenz.net/tools/svn"> <step id="checkout" description="Checkout source from repository"> <svn:checkout url="http://localhost:8181/svn/projname" path="${path}" revision="${revision}" /> </step> <step id="build" description="Builds the DITA sources"> <dop:dita config="project/dita2html.launch" quiet="true" /> </step> </build>

    A recipe is made of steps, the first step checks out the DITA sources from the Subversion repository. The following step uses a DITA-OP recipe command that executes an Eclipse launch configurations.

  7. Click on the Add platform button.
  8. Enter a target platform name but do not add any rule. This indicates that this build configuration is valid for any platform, you can call it “Any” or “All” as you like.
  9. Press the Add button.
  10. Press the Save button.
  11. Finally select the Active checkbox corresponding to the newly created configuration and finally press the Apply changes button.
Your build configuration is now ready to be executed, you can now start the build slave.


Running the build slave

  1. Open a Windows command line and go to the C:dita-op folder.
  2. Enter the slave projname command where projname is the name of the project for which you want the build to run.
  3. To stop the slave you will have to type the Ctrl-C key combination.
The build slave will run periodically whenever something changed in the Subversion repository. See The Bitten project for more information about Bitten and the build slave.

Reader's Comments

  1. David | 28 Jan 2009 14:29

    The links to localhost on this page have a typo in them: they point to locahost instead, which of course gives you a host not found error.

  2. Ben C | 05 Feb 2009 22:21

    I don’t know what the uptake has been on this package, but I have been able to set it up and use it quite easily.

    The only difficulty I had was using a WebDAV client to manipulate the repository. I kept getting 409 Conflict error messages whenever I tried to do anything.

    To fix the problem, I had to add this directive to the block in httpd.conf:

    SVNAutoversioning on

    Once I did that, it worked great.

    I would also love to see the Trac repository browser use an XML-aware diff. I’ll be looking into that and will comment if I get something working.

    Ben

    • Claude | 06 Feb 2009 15:30

      HI Ben,
      Thanks for the feedback, I will look into this SVNAutoversioning option and update the package accordingly.
      As for the xml-aware diff, keep me posted if you find anything.
      Claude

sidebartop

Pages

sidebarbottom
sidebartop

Links

sidebarbottom
sidebartop

Recent Comments

sidebarbottom
sidebartop

Archives

sidebarbottom
sidebartop

Meta

sidebarbottom
SourceForge.net Logo
© DITA Open Platform / Design: Smashing Wordpress Themes