Skip to content

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. The comments contain some more recent info others have had success with. Please leave a comment if you are successful with more recent versions.

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.

Read more from Uncategorized
30 Comments Post a comment
  1. Zen
    Sep 30 2012

    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.

    Reply
    • shane
      Sep 30 2012

      Thanks! I’ll play around with it when I get a chance.

      Reply
  2. Dorian
    Nov 16 2012

    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.

    Reply
  3. Dorian
    Nov 19 2012

    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…

    Reply
    • shane
      Nov 19 2012

      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.

      Reply
  4. Martin
    Jan 29 2013

    Shouldn’t it be:

    DocumentRoot /home/gitlab/gitlab/public

    Options -MultiViews

    ??

    Reply
    • shane
      Jan 29 2013

      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.

      Reply
      • Stephen Smith
        Oct 16 2013

        That should be noted in the instructions. Took me 30 minutes to realize why it was listing files. Not to sound mean or anything. Great guide! I just set up 6.1 in a subdomain. Took 3 hours total because of compile errors >_>

        Reply
        • Oct 18 2013

          Hi Stephen. Glad you got it working; what should be noted in the instructions though? I believe I changed all the instances of “gitlabhq” to “gitlab”.

          Reply
          • Stephen Smith
            Oct 22 2013

            In Martin’s comment:
            DocumentRoot /home/gitlab/gitlab/public

            In the steps:
            DocumentRoot /home/gitlab/gitlab

            The latter causes the files in the folder to be listed out instead of the application running. I guess I would have known it if I had used Ruby before :P

  5. Feb 15 2013

    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!

    Reply
    • shane
      Feb 16 2013

      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!

      Reply
  6. jose
    Mar 2 2013

    This was SUPER helpful

    Reply
  7. func0der
    Mar 3 2013

    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

    Reply
  8. tomato
    Jul 14 2013

    OMG, this was the 3rd day I’m trying to get this thing working with Apache and no progress.

    Your guide worked! Thank you! Thank you! Thank you! Thank you! Thank you!

    One thing is very strange…
    I didn’t find any “relative_url_root: /gitlab” line in my “/home/gitlab/gitlab/config/gitlab.yml” file. I searched on GitHub and found the file here:
    https://github.com/gitlabhq/gitlabhq/blob/master/config/gitlab.yml.example

    And it says
    # WARNING: This feature is no longer supported
    # Uncomment and customize to run in non-root path
    # Note that ENV['RAILS_RELATIVE_URL_ROOT'] in config/puma.rb may need to be changed
    # relative_url_root: /gitlab

    I didn’t expect it to work, but I added the “relative_url_root: /gitlab”
    line in the “gitlab” section of the “/home/gitlab/gitlab/config/gitlab.yml” file and worked.

    In case anyone else is interested I just want to mention some things. I did this on Ubuntu 10.04 Server Edition.

    One thing you can do to avoid the pain of the GitLab default installation instructions is to use the GitLab Recipes repository which is located here: https://github.com/gitlabhq/gitlab-recipes

    In this repo you can browse to “gitlab-recipes/install/v4/” and use the “ubuntu_server_1204.sh” script. PLEASE NOTE that this script will attempt to install it using nginx which on my Ubuntu 10.04 Server didn’t work. What I did was to comment everything after

    #==
    #== 7. Nginx
    #==

    And then start following this tutorial. I’m thinking to edit that script in order for it to make it work with Apache using this tutorial, hope I’ll manage.

    Good luck and thanks a lot!

    Reply
    • shane
      Jul 15 2013

      You’re very welcome! I’m glad to hear this still works since I haven’t touched GitLab in a while.

      Reply
  9. Jul 30 2013

    I am wondering, since you used GitLab 4.1 to install, there is a difference in using the 4.1 and master, mainly the usage of gitlabshell vs. gitolite.

    Which installation instructions did you used up to the nginx part, the 4.1 or master ?

    the provided link in your article referring to the installation guides is broken.

    Kind regards.

    Reply
    • shane
      Aug 1 2013

      I updated the link in the post to what appears to be the most recent version of the install guide.

      Reply
  10. gilles
    Jul 31 2013

    if gitlab say : not found : /

    sudo nano /etc/apache2/conf.d/gitlab :

    Alias /gitlab “/var/www/gitlab”
    SetEnv RAILS_RELATIVE_URL_ROOT “/gitlab”

    Options -MultiViews
    PassengerAppRoot “/home/git/gitlab”

    sudo nano /etc/apache2/httpd.conf :

    LoadModule passenger_module /usr/local/lib/ruby/gems/2.0.0/gems/passenger-4.0.10/buildout/apache2/mod_passenger.so
    PassengerRoot /usr/local/lib/ruby/gems/2.0.0/gems/passenger-4.0.10
    PassengerDefaultRuby /usr/local/bin/ruby

    sudo service apache2 restart

    Reply
    • shane
      Aug 1 2013

      Thanks gilles!

      Reply
  11. iDen
    Aug 14 2013

    Thanks for this freat HOWTO.
    It still works on:
    CentOS 6.4 x64
    GitLab 5.4
    GitLab-Shell v1.7.0
    Ruby 1.9.3-p448 (manual setup, + libyaml manual setup before ruby)
    Passenger-4.0.10

    Ok. GitLab works from suburi.
    But nothing else works.
    For example I have PhpMyAdmin as suburi as well.
    Disabling httpd gitlab.conf restores normal behavior.
    Tried to configure but not helped:
    – insert exact URL to proxy (as I understood it had to work like so, or I was wrong)
    ProxyPass / http://localhost:9292/ – indicate here /gitlab/*
    ProxyPassReverse / http://localhost:9292/ – same as above
    Tried to setup phpmyadmin.conf as VirtualHost or as just alias directory without virtualhost – no luck here as well.

    Any ideas or help will be much appreciated.

    My gitlab.conf

    # ServerName gitlab.office.dev
    ProxyRequests Off

    Order deny,allow
    Allow from 192.168

    ProxyPreserveHost On
    ProxyPass / http://localhost:9292/
    ProxyPassReverse / http://localhost:9292/
    DocumentRoot /var/www
    RailsBaseURI /gitlab
    Alias /gitlab /var/www/gitlab

    Options -MultiViews

    Reply
  12. iDen
    Aug 14 2013

    parser has removed directives from conf file :(

    Also just mentioned that projects wiki not working
    error 500 we’re sorry, but something went wrong …

    Reply
  13. Aug 23 2013

    I’m getting the following:

    Not Found:

    (Note the lack of the slash – I tried gilles solution but it did not work)

    Any ideas?

    Reply
  14. Jan Schlüter
    Sep 17 2013

    When following the installation guide for Gitlab 6.0 (except for the nginx part), the Gitlab backend will be served locally by unicorn. Passenger is not needed, Apache just needs to proxy requests to unicorn. The following is an example configuration for a subdirectory “/gitlab” on a http or https vhost, with gitlab installed to “/home/git/gitlab” and unicorn serving at port 8080:

    # gitlab configuration, put inside your vhost definition
    ProxyRequests Off
    ProxyPreserveHost On
    <Proxy *>
    Order deny, allow
    Allow from all
    </Proxy>
    Alias /gitlab /home/git/gitlab/public
    <Directory "/home/gitlab/gitlab/public">
    RewriteEngine On
    RewriteBase /gitlab/
    # if the requested file does not exist:
    RewriteCond %{REQUEST_FILENAME} !-f
    # then redirect to proxy by rewriting the URL:
    RewriteRule ^(.*)$ balancer://unicornservers/gitlab/$1 [P,DPI,L]
    </Directory>
    <Proxy balancer://unicornservers>
    BalancerMember http://127.0.0.1:8080
    ProxyPassReverse http://127.0.0.1:8080
    ProxyPassReverse http://www.yourdomain.foo:8080
    </Proxy>

    Reply
  15. Sep 25 2013

    Hi,

    I have been trying to get Gitlab working on a CentOS server that has Apache installed and running with many websites. It is also using CPanel so configuration files are automatically generated, almost untouchable.

    Without this tutorial, I would probably spend more days and even weeks. Thanks for such a great explanation. Now I have Gitlab running perfectly thanks to your help.

    Kind regards.

    Reply
  16. Yafu
    Dec 17 2013

    I don’t know why i can’t success using your method as

    DocumentRoot /var/www
    RailsBaseURI /gitlab

    Options -MultiViews

    to run gitlab in a subdirectory

    but I have changed as

    Alias /gitlab /var/www/gitlab
    SetEnv RAILS_RELATIVE_URL_ROOT “/gitlab”

    Options -MultiViews
    PassengerAppRoot “/home/git/gitlab”

    Still many thanks anyway.

    Reply
    • Dec 17 2013

      Hi Yafu, I can’t be of much help here unfortunately. I don’t use GitLab anymore and since it is so rapidly updated, these instructions are long out of date by now.

      Reply
      • Yafu
        Jan 6 2014

        yeah, but still thanks you for instructions, since your instructions directed me the right way.

        Reply
        • Jan 12 2014

          How did you manage to solve it Yafu? Mind sharing?

          Reply
          • Yafu
            Feb 3 2014

            Sorry to reply so late. I didn’t got Email notification, if you need more information you can directly send email to me.
            For my experience. I have integrate some of methods together. I’m not sure whether some of steps can affect the result or not. My steps are as follow:
            1. install gem passenger
            $ sudo gem install passenger
            $ sudo passenger-install-apache2-module
            2. After passenger installation, it will output a few lines need in this step.
            $ cd /etc/apache2/mods-available
            $ sudo nano passenger.load (and then, paste the lines generated in last step, mine is
            LoadModule passenger_module /usr/local/lib/ruby/gems/2.0.0/gems/passenger-4.0.29/buildout/apache2/mod_passenger.so
            PassengerRoot /usr/local/lib/ruby/gems/2.0.0/gems/passenger-4.0.29
            PassengerDefaultRuby /usr/local/bin/ruby)

            3. make a symlink from the current root of the web server to public directory in our Rails application.
            $cd /var/www
            $ln -s /home/git/gitlab/public gitlab (this line aims to link your gitlab location here)
            $chown www-data.www-data gitlab

            4. we need to tell Gitlab about the subdirectory.
            $cd /home/git/gitlab/config/
            then we need to uncomment settings in three files
            # 1) In your application.rb file: config.relative_url_root = “/gitlab”
            # 2) In your gitlab.yml file: relative_url_root: /gitlab
            # 3) In your unicorn.rb: ENV['RAILS_RELATIVE_URL_ROOT'] = “/gitlab”

            5. we need to change the directory in the Apache config

            $ sudo nano /etc/apache/sites-available/default

            then add
            Alias /gitlab /var/www/gitlab
            SetEnv RAILS_RELATIVE_URL_ROOT “/gitlab”

            Options -MultiViews
            PassengerAppRoot “/home/git/gitlab”

            6. After finished all questions above, you can restart your apache2 server, it will work.
            $ sudo service apache2 restart.

            7(optional) I not sure whether the modules below need to enabled. you can try
            $sudo a2enmod pessanger
            $sudo a2enmod proxy
            $sudo a2enmod proxy_balancer

            The last, good luck to you

Leave a comment.

(required)
(required)

Note: HTML is allowed. Your email address will never be published and is only used for notification of comment replies by the blog owner.