Running GitLab from a subdirectory on Apache

Note: As of February 2013, these instructions have been tested with GitLab 4.1. GitLab evolves very rapidly and I do not use it anymore so these instructions will quickly become outdated.

I’ve been looking for a good git manager website that I could install on my own server. A few days ago I found GitLab, which does everything I need it to do and more. The only problem is that the setup guides use Nginx as a webserver. I’m cheap and only have one server, which runs Apache. I also have this Wordpress (this blog) already running on my server so I would like have to install GitLab to a subdirectory too.

Part 1: Running GitLab on Apache

First, let’s talk about running GitLab from Apache. Everything to get Gitlab running on Apache is exactly the same if you’re following the install guides for GitLab, up until the point of installing Nginx. So, if you haven’t started install GitLab yet, go do that and stop when you get to installing Nginx.

I assume you already have Apache installed and up and running, if not, there are more than enough guides floating around on how to do this. I won’t add another to the fray.

GitLab is a Ruby on Rails application and to run it on Apache we need to install the Passenger module.

1
2
$ sudo gem install passenger
$ sudo passenger-install-apache2-module

After installing the Passenger Apache module, it will output a few lines that need put in your Apache config. They should look something like the following, but do not copy and paste these! Use the ones that are output by the installation script!

1
2
3
LoadModule passenger_module /usr/local/lib/ruby/gems/1.9.1/gems/passenger-3.0.19/ext/apache2/mod_passenger.so
PassengerRoot /usr/local/lib/ruby/gems/1.9.1/gems/passenger-3.0.19
PassengerRuby /usr/local/bin/ruby

Go ahead and open /etc/apache2/httpd.conf, or whatever Apache config you’re using and drop them in there. Last step is to tell Apache where to look for GitLab. Open the Apache site config file you’re using, usually /etc/apache2/sites-available/default and add the following inside the VirtualHost tags:

1
2
3
4
DocumentRoot /home/gitlab/gitlab
<Directory /home/gitlab/gitlab>
    Options -MultiViews
</Directory>

As per the GitLab install guide, it should be sitting at “/home/gitlab/gitlab”, or similar. Change this if this is not your case.

Now restart Apache and GitLab should fire up! Note that when first starting GitLab, the page might take a minute or so to load while the server starts GitLab. Keep reading if you want to install GitLab to a subdirectory.

Part 2: Running GitLab from a subdirectory

Like I mentioned above, maybe you have another site on your server and want GitLab in a subdirectory. Easy enough. The Passenger documentation has info on how to deploy a Rails application to a subdirectory, but it's a little confusing. First thing we need to do is make a symlink from the current root of the web server to the public directory in our Rails application. I'm using the standard /var/www for my server; change it if you're using something different.

1
2
3
$ cd /var/www
$ ln -s /home/gitlab/gitlab/public gitlab
$ chown www-data.www-data gitlab

Now we need to tell GitLab about the subdirectory. Open /home/gitlab/gitlab/config/gitlab.yml and uncomment:

1
relative_url_root: /gitlab

One more thing to change, we need to change the directory in the Apache site config we added above. Open /etc/apache2/sites-available/default and make the following changes:

1
2
3
4
5
6
7
8
9
10
11
12
# Change:
DocumentRoot /home/gitlab/gitlab
<Directory /home/gitlab/gitlab>
    Options -MultiViews
</Directory>

# To:
DocumentRoot /var/www
RailsBaseURI /gitlab
<Directory /var/www/gitlab>
    Options -MultiViews
</Directory>

The magic line here is the RailsBaseURI directive. This instructs Passenger to expect a subdirectory, instead of the root of the server. Restart Apache and you should be up and running!

One small snag I ran into was that since I was running Wordpress at the server root and Wordpress makes use of mod_rewrite to change the URL's around, it was interfering with GitLab. Fortunately, this is a very simple fix. In the public directory of GitLab, create an .htaccess file with the contents:

1
RewriteEngine off

Now, restart Apache and that's all.