This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:
Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.
See Instead: This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.
Git and GitHub are awesome tools that make managing and administering lots of Git repositories and their associated permissions a breeze. This is wonderful if you’re writing open source software, but when writing closed source software you may not want to trust your code to a third party server. So how can you get the control, flexibility and ease of use of something like Github or BitBucket without hosting your git repositories on servers outside of your control?
Enter GitLab. GitLab provides a simple but powerful web based interface to your Git repositories a la GitHub, only you can host it on your own cloud server, control access as you see fit, and repo size is limited only by how much storage space your server has. This tutorial will walk you through setting up a DigitalOcean VPS as a GitLab server.
Note: This tutorial explains how to install GitLab from source. When originally written, this was the only option. Today, it is much simpler to get it up and running using the GitLab’s “omnibus” package. You can also launch a GitLab droplet on DigitalOcean in one click with our application image.
This tutorial assumes you’re using a brand new Ubuntu 12.04 VPS. We’ll be installing all the necessary software needed to make GitLab work. If you are using an existing VPS (droplet) or a different Linux distro you may have issues, especially with incompatible Python and Ruby versions. Make sure you have Ruby 2.0 and Python 2.7 installed before beginning.
The first step is to install some required packages:
sudo apt-get update
sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl git-core openssh-server redis-server checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libicu-dev
Make sure you don’t have Ruby 1.8 installed (on a default Ubuntu 12.04 VPS it won’t be).
Install Ruby 2.0 (this will take a while):
mkdir /tmp/ruby && cd /tmp/ruby
curl --progress ftp://ftp.ruby-lang.org/pub/ruby/2.0/ruby-2.0.0-p247.tar.gz | tar xz
sudo make install
When it’s finished you can check to make sure that you have Ruby 2 (not 1.8) installed by doing a:
If the output looks like the below then you’re good:
ruby 2.0.0p247 (2013-06-27 revision 41674) [x86_64-linux]
Now we need to install the Bundler gem:
sudo gem install bundler --no-ri --no-rdoc
And create a git user for GitLab to use:
sudo adduser --disabled-login --gecos 'GitLab' git
Download the GitLab shell with the following commands:
sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git
sudo -u git -H git checkout v1.7.0
sudo -u git -H cp config.yml.example config.yml
You now have a copy of GitLab Shell 1.7.0, and the example
config.yml is ready to go.
If you have a domain name pointed at this VPS, then you should take the time to edit
config.yml to use this domain.
Near the top there will be a line that looks like:
http://localhost/ portion to match your domain name. So if your domain is www.YOURDOMAIN.com the line should look like this:
Now you can run the GitLab shell installer:
sudo -u git -H ./bin/install
We’ll set up GitLab to use a MySQL backend. The first step is to install MySQL with the below command. During the install process it will ask you to set a MySQL root password. Set it to whatever you like, but note it down as you will need it for the next steps.
sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
MySQL is now installed and the root password is set to the value you chose in the last step. We now need to create a MySQL user for GitLab to use. To do this we’ll first save the necessary SQL queries to a temporary file. Type:
Paste in the following, changing the
$password on the first line to a real password. Keep track of this password as this will be your GitLab’s database password.
CREATE USER 'gitlab'@'localhost' IDENTIFIED BY '$password';
CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
GRANT SELECT, LOCK TABLES, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost';
Now save the file and execute the following command (entering your MySQL root password from the first step at the prompt) to have MySQL execute your queries:
cat tempfile | mysql -u root -p
To make sure your new MySQL user was created successfully let’s log in to
mysql using the
mysql -u gitlab -p
If you see some text followed by a:
line then everything worked successfully. Go ahead and type:
mysql> prompt to exit MySQL, and delete the
tempfile file since it contains a password:
At this point we have everything configured to install GitLab successfully, so let’s proceed with the installation:
sudo -u git -H git clone https://github.com/gitlabhq/gitlabhq.git gitlab
sudo -u git -H git checkout 6-0-stable
sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml
Just like we did with the GitLab shell set up, if you have a domain configured for your VPS we need to edit the
config.yml to use that domain.
sudo -u git -H nano config/gitlab.yml
Near the top of the file you should a text block that looks like the following:
## Web server settings
host: entry to match your domain name. If your domain is www.YOURDOMAIN.com, then it should look like this:
## Web server settings
Let’s also set some linux file permissions, configure the
git user’s Git config, and set up some GitLab config and directories for the
sudo chown -R git log/
sudo chown -R git tmp/
sudo chmod -R u+rwX log/
sudo chmod -R u+rwX tmp/
sudo -u git -H mkdir /home/git/gitlab-satellites
sudo -u git -H mkdir tmp/pids/
sudo -u git -H mkdir tmp/sockets/
sudo chmod -R u+rwX tmp/pids/
sudo chmod -R u+rwX tmp/sockets/
sudo -u git -H mkdir public/uploads
sudo chmod -R u+rwX public/uploads
sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb
sudo -u git -H git config --global user.name "GitLab"
sudo -u git -H git config --global user.email "gitlab@localhost"
sudo -u git -H git config --global core.autocrlf input
sudo -u git cp config/database.yml.mysql config/database.yml
Now we need to tell GitLab to use the
gitlab MySQL user we set up earlier. To do this, edit the
sudo -u git -H nano config/database.yml
Near the top there will be a section called
production: which will contain
password entries. By default it looks like this:
password: "secure password"
password entries to match the GitLab database user we set up earlier. So if the password you used for your GitLab MySQL user was
$password the edited file should look like this:
Save the file, and we’ll secure it so that other users of the server can’t see the password:
sudo -u git -H chmod o-rwx config/database.yml
Let’s install a few more needed gems (this step may take awhile):
sudo gem install charlock_holmes --version '0.6.9.4'
sudo -u git -H bundle install --deployment --without development test postgres aws
And run some final setup (type yes when it asks if you want to continue):
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
After this finishes it will print a lot of information onscreen and at the end will show
Administrator account created and give you your administrator credentials. It should look something like the below:
Administrator account created:
Now let’s set GitLab to start up whenever your server boots:
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
sudo chmod +x /etc/init.d/gitlab
sudo update-rc.d gitlab defaults 21
Run the following to make sure everything is working:
sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
If there are no error messages and the data outputted by that command looks right then your GitLab install is working. Almost finished! Start up GitLab with this command:
sudo service gitlab start
GitLab works with the nginx web server by default. If you already have your own web server such as Apache set up then these steps don’t apply. Check out these recipes for info on how to configure GitLab with other web servers. Otherwise follow these directions to install and configure nginx to work with GitLab:
sudo apt-get -y install nginx
sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
/etc/nginx/sites-available/gitlab to use your domain name:
sudo nano /etc/nginx/sites-available/gitlab
A little ways from the top of the file you will see an entry
server_name which is set to
YOUR_SERVER_FQDN. As in the previous steps, replace the
YOUR_SERVER_FQDN with your domain name. The original file looks like this:
listen *:80 default_server; # e.g., listen 192.168.1.1:80; In most cases *:80 is a good idea
server_name YOUR_SERVER_FQDN; #
If your domain is www.YOURDOMAIN.com then you should change it to look like this:
listen *:80 default_server; # e.g., listen 192.168.1.1:80; In most cases *:80 is a good idea
server_name www.YOURDOMAIN.com; #
And restart nginx:
sudo service nginx restart
Voila! You’re done. Connect to GitLab via your web browser using the Admin login and password from above (default user:
5iveL!fe) and enjoy GitLab.
If you are using a 512MB VPS then due to GitLab’s memory requirements it’s quite likely you will run into a
502 Bad Gateway error. If that’s the case, read on…
In a perfect world GitLab would now be running perfectly. Unfortunately, GitLab has surprisingly high memory requirements, so on 512MB VPSs it often chokes on the first sign in. This is because GitLab uses a lot of memory on the very first login. Since the Ubuntu 12.04 VPS has no swap space when the memory is exceeded parts of GitLab get terminated. Needless to say GitLab does not run well when parts of it are being unexpectedly terminated.
The easiest solution is just to allocate more memory to your VPS, at least for the first sign in. If you don’t want to do that, another option is to increase swap space. DigitalOcean already has a full tutorial on how to do this available here (although I would recommend adding more than just 512MB of swap). The quick fix is to run the following:
sudo dd if=/dev/zero of=/swapfile bs=1024 count=1024k
sudo mkswap /swapfile
sudo swapon /swapfile
Your swapfile is now running and active, but to set it so that it’s activated on each boot we need to edit
sudo nano /etc/fstab
Paste the following onto the bottom of the file:
/swapfile none swap sw 0 0
Now restart your VPS:
Wait a minute or two for your VPS to reboot, and then try GitLab again. If it doesn’t work the first time, refresh the Bad Gateway page a couple of times, and you should soon see the GitLab login page.
<div class=“author”>Submitted by: Nik van der Ploeg</div>
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.