How To Set Up GitLab As Your Very Own Private GitHub Clone

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:

1. Check out the excellent Gitlab installation documentation here.
2. And for info on the 502 bad gateway error, check this thread.

<div class=“author”>Submitted by: Nik van der Ploeg</div>

/usr/local/bin/ruby extconf.rb