Running GitLab from a subdirectory on Apache
Note: As of February 2013, these instructions have been tested with GitLab 4.1.
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 have to install GitLab to a subdirectory.
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.
$ 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!
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:
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.
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.
$ 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:
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:
# 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 interferring with GitLab. Fortunately, this is a very simple fix. In the public directory of GitLab, create an .htaccess file with the contents:
RewriteEngine off
Now, restart Apache and that’s all.
Hi,
Many thanks for this guide, it really helped me out.
For your situation about the cache, I found a workaround.
if your subdiretory is subDir
Set assets prefix to /suDir/assets
Create folder under public, named subDir, with write permissions.
Then, precompile your assets for production.
Load page, nothing works. Revert changes, then everything works, because the assets needed got precompiled under the correct folder.
Best regards.
Thanks! I’ll play around with it when I get a chance.
Thanks for the guide, it works nicely.
With the workaround for the assets everything also looks as it should.
As it took me a bit to figure out what I had to do exactly for the workaround, here are the steps in full:
assumptions:
- you’re gitlab installation resides under ~/gitlab of the gitlab user
- you’re running gitlab under the sub-uri “subDir”
steps (all to be performed as the gitlab user):
- edit ~/gitlab/config/production.rb and add this line near the other assets lines: config.assets.prefix = ‘/git/assets’
$ cd ~/gitlab
$ mkdir public/subDir
$ RAILS_ENV=production rake assets:precompile
- wait a while for it to finish
- check that there is now a directory with lot of stuff at ~/gitlab/public/subDir/assets
Now it should work just fine.
After flushing my browser cache I realized that some assets could still not be accessed.
So I added a symlink in “~/gitlab/public” named “assets” pointing to “subDir/assets” and this seems to solve the remaining problems.
Although this is not a really clean setup, with the assets being available through two different URLs, it now actually works…
Hi Dorian, thanks for info! That makes sense. I was trying your instructions above and couldn’t get it to work. Last night, however, I put GitLab 3.0.2 on my server and noticed that the assets now show properly in a subdirectory without any config changes.
Shouldn’t it be:
DocumentRoot /home/gitlab/gitlab/public
Options -MultiViews
??
Hi Martin,
When this post was written, the Gitlab install guide instructed putting Gitlab at /home/gitlabhq/gitlabhq. With the current install guide, yes, the path should be /home/gitlab/gitlab/public.
I just wanted to say thank you as well.
This post has saved me hours or work getting apache and nginx to play nice together.
Could I suggest you update the text body to reflect the change from /home/gitlab/gitlab to /home/gitlab/gitlab/public
Otherwise, Thank you!
Hi Stuart, I’m glad you found it useful!
When you say change “/home/gitlab/gitlab to /home/gitlab/gitlab/public” did you mean when creating the symlink “$ ln -s /home/gitlab/gitlab/public gitlab”? If so, yes, that was an error and has been fixed. Thanks!
This was SUPER helpful
A little annotation.
Since Ruby2.0 you actually need to clone passenger from repository to make it work.
Neither the beta nor the stable is compatible to Ruby2.0.
Referring to this bug report:https://github.com/FooBarWidget/passenger/pull/71
Tried cloning and compiling it myself. Works perfectly ;)
Thanks for you tutorial. Took me hours to figure out how to run GitLab with apache. I am not a ruby guy though :P
Greetings
func0der