How To Setup A Fossil Server

Fossil is a light-weight DVCS that can be easily used on the web through the brilliant web server nginx.

Introduction

If you've ever done professional software development, you already know that it is not possible without source control and issue tracking software. In this article, you will see how easy it is to setup a fully working Fossil DVCS server on a CentOS machine.

FreeBSD users may find this guide (external) more useful.

Installing Fossil

To be able to use the latest Fossil version, we're going to install it from the source.

Installing compile-timed requirements

Fossil can use zlib and openssl (for HTTPS access). It can also be extended through a pseudo-macro mechanism using Tcl scripting language. Install all of them to enable all features -don't worry! They require only a tiny space and don't drag in a jungle of dependencies.

# yum install zlib zlib-devel tcl tcl-devel openssl openssl-devel

Compiling and installing fossil

Obtain Fossil source from Fossil website, extract it, run ./configure followed by make install and you're done. For example:

# wget 'http://www.fossil-scm.org/download/fossil-src-20121022124804.tar.gz'   # change this address to get the latest release sources
# tar zxf fossil-src-20121022124804.tar.gz   # change this if you changed the address above
# cd fossil-src-20121022124804   # you may need to change this too
# ./configure --json --with-tcl --with-zlib --with-openssl
# make install

By default Fossil binary will be installed to /usr/local/bin, unless you pass the --prefix option to configure script.

To test your installation, just run fossil help.

# fossil help
Usage: fossil help COMMAND
Common COMMANDs:  (use "fossil help --all" for a complete list)
add         clean       gdiff       merge       revert      tag       
addremove   clone       help        mv          rm          timeline  
all         commit      import      open        settings    ui        
annotate    diff        info        pull        sqlite3     undo      
bisect      export      init        push        stash       update    
branch      extras      jsotn        rebuild     status      version   
changes     finfo       ls          remote-url  sync      
This is fossil version 1.24 [8d758d3715] 2012-10-22 12:48:04 UTC

Setting up xinetd

First you need to install xinted.

# yum install xinetd

Now assuming that Fossil server is supposed to run on 4545, we need to inform xinted about it.

# echo 'fossil   4545/tcp' >> /etc/services

The last step is telling how to invoke fossil with which parameters. Create a file named fossil in /etc/xinted.d with the following content:

# /etc/xinetd.d/fossil 
service fossil
{
        type = UNLISTED
        socket_type = stream
        protocol = tcp
        wait = no
        user = root
        disable = no
        server = /usr/local/bin/fossil

        # HTTP port to listen to (the same as the one in '/etc/services')
        port = 4545
        # The path that the Fossil repos are stored
        server_args = http /srv/fossil
        # Restrict access
        only_from = 127.0.0.1 localhost
}

That's done it. Start xinetd.

# service xinetd start

Setting up nginx

If you have already enabled EPEL repository on your CentOS 6.x, you may notice that there's already an nginx package available at version 1.0.15 which is the legacy stable version of nginx. To use the latest version, add the nginx repository for your CentOS (5 or 6) according to nginx docs and then install nginx itself. For example on a CentOS 6.x machine:

# rpm -Uhv http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm
# yum install nginx

To configure nginx to forward requests to the fossil server, create a file in /etc/nginx/conf.d/ with the following content:

# /etc/nginx/conf.d/fossil.conf

upstream dev_bahmanm_com {
        server  127.0.0.1:4545;
}

server {
    listen       80;
    server_name  dev.bahmanm.com dev;  # change this to your own domain name

    location / {
        proxy_pass              http://dev_bahmanm_com;
        proxy_set_header        Host            $host:$server_port;
        proxy_set_header        X-Real-IP       $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Finally start the nginx server.

# service nginx start

Create your first repository

To test your setup, create your first repository in /srv/fossil (or whatever path you picked in /etc/xinetd.d/fossil):

# cd /srv/fossil
# fossil init --user admin -A admin test.fossil
project-id: a7fdf1d27b0b6fb3993404c7eadbb9450dd22618
server-id:  69fb1ad32b2d1e527dc1d6ac3e322e0fd3c00e16
admin-user: admin (initial password is "8d1347")

Now you can navigate to http://YOURHOST/test and see that your fossil repository is available on the web!

Note: When creating the repository, it is mandatory that the name ends in ".fossil".

You may also want to enable nginx and xinetd to run automatically at startup.

# chkconfig --level 345 nginx on
# chkconfig --level 345 xinetd on

Conclusion

You can setup a web-enabled source control, issue tracking and wiki solution using Fossil and nginx very quickly and with minimal administration effort. The good thing is that Fossil is extremely light-weight compared to similar solutions like Trac -something that you'll come to appreciate when the number of your projects grows.

Image source: dianastaresinicdeane.files.wordpress.com

Search...

Bahman's Musings