Installing CVSTrac

Getting The CVSTrac Executable

The first thing you need to do is either download or compile the cvstrac executable. You can install the executable wherever you like. For the rest of these instructions we will assume that cvstrac is installed in /usr/bin.

Note that the name of the executable depends on the target SCM. For SvnTrac, it's svntrac. For GitTrac, it's gittrac. Otherwise, installation is largely the same process.

CVSTrac Dependencies

The cvstrac executable is mostly standalone. But it does require (for CVS) the support of a few external programs:

These files are usually packaged with RCS, which can be downloaded at this address:

However, any installation that already has CVS installed likely also contains all of the above executables as well. So these dependencies are not normally an issue.

Initializing The CVSTrac Database

CVSTrac contains its own embedded SQL database engine, so no external RDBMS support is required. The entire database for a single project is stored in a single file on disk. The first step toward getting CVSTrac running is to create and initialize this database.

To initialize a new CVSTrac database, type the following command (must be a user other than root to initialize):

    cvstrac init /home/cvs demo

Replace the "/home/cvs" argument with the name of the directory where you want the database to reside. Replace the "demo" argument with the name of the project that CVSTrac will be hosting. The database file that is created will be named "/home/cvs/demo.db".

NOTE: If the CVSTrac web server is already running, you must first stop it before attempting to use the init command.

Three Types Of Installation

CVSTrac can be run in three different ways:

To run CVSTrac off of inetd make an entry like the following in your /etc/inetd.conf file:

   80 stream tcp nowait.1000 cvs /usr/bin/cvstrac cvstrac http /home/cvs

Then restart you inetd daemon. For xinetd, create a file named /etc/xinetd.d/http with the following content:

   service http
     socket_type = stream
     wait        = no
     user        = cvs
     server      = /usr/bin/cvstrac
     server_args = http /home/cvs

Once again, you will need to restart your xinetd daemon after making this change. In both cases above, the user id of the cvstrac process is specified to be "cvs". This user must be one that has read access to the CVS repository. Some features (the ability to modify the CVSROOT/passwd file using the CVSTrac setup pages) require that the user have write access as well. You may substitute a different user in place of "cvs" if necessary. You can make other substitutions to chose different TCP port numbers, installation directories, etc., according to the needs of your site.

To run CVSTrac out of a CGI script, create the appropriate CGI script "run-cvstrac" like this:

    /usr/bin/cvstrac.bin cgi /home/cvs

You must use permission bits or the suEXEC extension to insure that the cvstrac binary is run as a user that has read access to the CVS repository.

To run CVSTrac as its own webserver, execute a command like this:

    cvstrac server 8008 /home/cvs

The 8008 is the TCP port that the webserver will listen on for incoming TCP/IP connections. (Note : You MUST run cvstrac in the CVSROOT of the CVS projects, for example '/home/cvs/CVSROOT' -and- a folder of the exact name of the project must also exist at the same level)

If you choose a port number below 1024, you will have to launch cvstrac as root. But you do not want to run the process as root when it is serving pages. You can get around this by changing the user ID after the listing TCP socket is opened, as follows:

    cvstrac chroot / cvs server 80 /home/cvs

The first three arguments ("chroot", "/", and "cvs") cause the cvstrac binary to do a chroot to directory / (which is a no-op) and then drop root privileges to become the user cvs. But the root privileges are not dropped until after the socket is opened for listing on port 80. For added security, you can run CVSTrac in a chroot jail by specifying a directory other than "/" in the command above. See ChrootJailForCvstrac for details.

Configuring Your Installation

After you get CVSTrac listening for incoming HTTP requests, you'll need to configure the server for your particular installation. This is done using built-in web pages. Log into your new CVSTrac server as user "setup" with password "setup". (You'll want to change the password as soon as possible, by the way.) The URL to use is


if you are using the inetd, xinetd, or web-server invocation methods. Substitute the correct hostname and port in place of "localhost:8008" and the correct project name in place of "demo". If you are using the CGI invocation method, then the URL will look more like this:


Once again, substitute the correct hostname and TCP port in place of "localhost", the name of your CGI script in place of "cgi-bin/run-cvstrac", and the name of your project in place of "demo".

After you get logged in, change the "setup" password, enter the location of the CVS repository that you want to track, configure other options, and you are ready to go.

Note: CVSTrac only knows about files that appear in the CVSROOT/history log. The "cvs import" command does not make entries in this log. Only the "cvs commit" command does. Hence you can only see files that have been processed by "cvs commit", not just "cvs import". (For more information see the FrequentlyAskedQuestions page)

Multiple Projects On One Host

If you want to host more than one project, just create additional CVSTrac databases in the same directory as the first database. Then log and configure each database separately. For example, to create projects "demo2" and "demo3", first execute these commands:

   cvstrac init /home/cvs demo2
   cvstrac init /home/cvs demo3

Then log into each project using a web-browser and configure the project as necessary.