Status: Deprecated
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:
Upgrade to Ubuntu 14.04.
Upgrade from Ubuntu 14.04 to Ubuntu 16.04
Migrate the server data to a supported version
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.
Introduction
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
cd ruby-2.0.0-p247
./configure
make
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:
ruby --version
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
Installing the GitLab Shell
Download the GitLab shell with the following commands:
cd /home/git
sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git
cd gitlab-shell
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.
nano config.yml
Near the top there will be a line that looks like:
gitlab_url: "http://localhost/"
Change the http://localhost/ portion to match your domain name. So if your domain is www.YOURDOMAIN.com the line should look like this:
gitlab_url: "http://www.YOURDOMAIN.com/"
Now you can run the GitLab shell installer:
sudo -u git -H ./bin/install
Database Setup
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:
nano tempfile
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 gitlab user:
mysql -u gitlab -p
If you see some text followed by a:
mysql>
line then everything worked successfully. Go ahead and type:
exit;
at the mysql> prompt to exit MySQL, and delete the tempfile file since it contains a password:
rm tempfile
At this point we have everything configured to install GitLab successfully, so let’s proceed with the installation:
cd /home/git
sudo -u git -H git clone https://github.com/gitlabhq/gitlabhq.git gitlab
cd /home/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:
gitlab:
## Web server settings
host: localhost
port: 80
https: false
Change the host: entry to match your domain name. If your domain is www.YOURDOMAIN.com, then it should look like this:
gitlab:
## Web server settings
host: www.YOURDOMAIN.com
port: 80
https: false
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 git user:
cd /home/git/gitlab
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 config/database.yml file:
sudo -u git -H nano config/database.yml
Near the top there will be a section called production: which will contain username and password entries. By default it looks like this:
production:
adapter: mysql2
encoding: utf8
reconnect: false
database: gitlabhq_production
pool: 10
username: root
password: "secure password"
Change the username and 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:
production:
adapter: mysql2
encoding: utf8
reconnect: false
database: gitlabhq_production
pool: 10
username: gitlab
password: "$password"
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):
cd /home/git/gitlab
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:
login.........admin@local.host
password......5iveL!fe
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
Setting Up NGINX
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
cd /home/git/gitlab
sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
Edit /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:
server {
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:
server {
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: admin@local.host, pass: 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…
Troubleshooting
502 Bad Gateway Error
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 /etc/fstab:
sudo nano /etc/fstab
Paste the following onto the bottom of the file:
/swapfile none swap sw 0 0
Now restart your VPS:
sudo restart
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.
References:
Check out the excellent Gitlab installation documentation here.
And for info on the 502 bad gateway error, check this thread.
