Terry : GitLab

What is GitLab?

Installation

Overview

Packages / Dependencies

Ruby

System Users

For 4.x

For 5.x and later

Gitolite (for 4.x ONLY)

GitLab Shell

Database

MySQL

PostgreSQL

GitLab

Install GitLab into home directory of the user "gitlab"

Clone from source

Configure GitLab

Config GitLab Database Settings

Install Gems

Configure Git

Setup GitLab Hooks (4.x ONLY)

Initialize Database and Activate Advanced Features

Check Application Status

Install Init Script

Nginx

Installation

Site Configuration

Add Nginx user to git group

Restart Nginx

Try out GitLab

Update from a previous version

From 4.0 to 4.1

Stop gitlab service

Update GitLab

Update Gitolite

Tips

Reference

What is GitLab?

GitLab is self hosted Git management software.

GitLab allows you to

keep your code secure on your own server
manage repositories, users and access permissions
communicate through issues, line-comments and wiki pages
perform code review with merge requests

GitLab is

powered by Ruby on Rails
completely free and open source (MIT license)
used by more than 10.000 organizations to keep their code secure

Requirements

Ubuntu or Debian
Ruby 1.9.3+
MySQL or PostgreSQL
git
gitlab-shell (5.0+)
gitolite (up to 4.2)
redis

Installation

Overview

The GitLab installation consists of setting up th following components

Packages / Dependencies
Ruby
System Users
Gitolite
Database
GitLab
Nginx

Installation Guide for production servers: https://github.com/gitlabhq/gitlabhq/blob/master/doc/install/installation.md

4.0 stable installation guide (on which this wiki was initially based): https://github.com/gitlabhq/gitlabhq/blob/4-0-stable/doc/install/installation.md

NOTE: Since 5.0, GitLab has moved to its own GitLab Shell to replace gitolite.

Packages / Dependencies

Install the required packages

sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev \
    libgdbm-dev libreadline-dev libncurses5-dev libffi-dev wget curl git \
    openssh-server redis-server checkinstall libxml2-dev libxslt-dev \
    libcurl4-openssl-dev libicu-dev

Make sure you have the right version of Python installed.

# Install Python
sudo apt-get install -y python

# Make sure that Python is 2.5+ (3.x is not supported at the moment)
python --version

# If it's Python 3 you might need to install Python 2 separately
sudo apt-get install python2.7

# Make sure you can access Python via python2
python2 --version

# If you get a "command not found" error create a link to the python binary
sudo ln -s /usr/bin/python /usr/bin/python2

In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 whereas Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with

sudo apt-get install -y postfix

Then select 'Internet Site' and press enter to confirm the hostname.

Ruby

Use rbenv / ruby-build (recommended) or RVM to install (compile from source).

NOTE: Install Ruby for gitlab user.

rbenv install 1.9.3-p448 -v

Install bundler gem

gem install rbenv-rehash bundler --no-ri --no-rdoc
# Optional
gem update --system

System Users

For 4.x

Create a user for Git and Gitolite

# 4.0
# sudo adduser --system --shell /bin/sh --gecos 'Git Version Control' --group --disabled-password --home /home/git git

OR

sudo adduser \
  --system \
  --shell /bin/sh \
  --gecos 'Git Version Control' \
  --group \
  --disabled-password \
  --home /home/git \
  git

Create a user for GitLab

NOTE: install Ruby again for gitlab user if you use rbenv to install Ruby.

sudo adduser --disabled-login --gecos 'GitLab' gitlab

# Add it to the git group
sudo usermod -a -G git gitlab

# Generate the SSH key
sudo -u gitlab -H ssh-keygen -q -N '' -t rsa -f /home/gitlab/.ssh/id_rsa

For 5.x and later

NOTE: GitLab 5.0+ uses GitLab Shell instead of gitolite.

sudo adduser --disabled-login --gecos 'GitLab' git

Gitolite (for 4.x ONLY)

Clone GitLab's fork of the Gitolite source code

cd /home/git
sudo -u git -H git clone -b gl-v320 https://github.com/gitlabhq/gitolite.git /home/git/gitolite

Setup Gitolite with GitLab as its admin

Important Note: GitLab assumes full and unshared control over this Gitolite installation.

# Add Gitolite scripts to $PATH
sudo -u git -H mkdir /home/git/bin
sudo -u git -H sh -c 'printf "%b\n%b\n" "PATH=\$PATH:/home/git/bin" "export PATH" >> /home/git/.profile'
sudo -u git -H sh -c 'gitolite/install -ln /home/git/bin'

# Copy the gitlab user's (public) SSH key ...
sudo cp /home/gitlab/.ssh/id_rsa.pub /home/git/gitlab.pub
sudo chmod 0444 /home/git/gitlab.pub

# ... and use it as the admin key for the Gitolite setup
sudo -u git -H sh -c "PATH=/home/git/bin:$PATH; gitolite setup -pk /home/git/gitlab.pub"

Fix the directory permissions for the configuration directory

# Make sure the Gitolite config dir is owned by git
sudo chmod 750 /home/git/.gitolite/
sudo chown -R git:git /home/git/.gitolite/

Fix the directory permissions for the repositories

# Make sure the repositories dir is owned by git and it stays that way
sudo chmod -R ug+rwXs,o-rwx /home/git/repositories/
sudo chown -R git:git /home/git/repositories/

~~Disable StrictHostKeyChecking for localhost and your domain~~

Check the better solution below => Add domains to the list of know hosts

echo "Host localhost
   StrictHostKeyChecking no
   UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config

echo "Host DOMAIN_NAME
   StrictHostKeyChecking no
   UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config

# If gitolite domain differs
echo "Host YOUR_GITOLITE_DOMAIN
   StrictHostKeyChecking no
   UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config

Add domains to the list of known hosts

sudo -u gitlab -H ssh git@localhost
sudo -u gitlab -H ssh git@YOUR_DOMAIN_NAME
sudo -u gitlab -H ssh git@YOUR_GITOLITE_DOMAIN_NAME

Test if everything works so far

# Clone the admin repo so SSH adds localhost to known_hosts ...
# ... and to be sure your users have access to Gitolite
sudo -u gitlab -H git clone git@localhost:gitolite-admin.git /tmp/gitolite-admin

# If it succeeded without errors you can remove the cloned repo
sudo rm -rf /tmp/gitolite-admin

Important Note: If you can't clone the gitolite-admin repository: DO NOT PROCEED WITH INSTALLATION! Check the Trouble Shooting Guide and make sure you have followed all of the above steps carefully.

GitLab Shell

GitLab Shell is a ssh access and repository management software developed specially for GitLab.

# Go to home directory
cd /home/git
# Clone gitlab shell
sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git
cd gitlab-shell
# switch to right version - for 5.4
sudo -u git -H git checkout v1.5.0
sudo -u git -H cp config.yml.example config.yml
# Edit config and replace gitlab_url
# with something like 'http://domain.com/'
sudo -u git -H editor config.yml
# Do setup
sudo -u git -H ./bin/install

NOTE: GitLab and GitLab Shell versions table

GitLab Version	gitlab-shell version
5.0	v1.1.0
5.1	v1.3.0
5.2	v1.4.0
5.3	v1.4.0
5.4	v1.5.0
6.0	v1.7.0

Database

GitLab supports the following databases

MySQL (preferred)
PostgreSQL

MySQL

Install the database packages

sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev

Login to MySQL

mysql -u root -p

Create a user for GitLab. (change $password to a real password)

mysql> CREATE USER 'gitlab'@'localhost' IDENTIFIED BY '$password';

Create the GitLab production database

mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;

Grant the GitLab user necessary permissions on the tables

mysql> GRANT SELECT, LOCK TABLES, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost';

Quit the database session

mysql> \q

Try connecting to the new database with the new user

sudo -u git -H mysql -u gitlab -p -D gitlabhq_production

PostgreSQL

For PostgresQL

# Install the database packages
sudo apt-get install -y postgresql-9.1 libpq-dev

# Login to PostgreSQL
sudo -u postgres psql -d template1

# Create a user for GitLab. (change $password to a real password)
template1=# CREATE USER git WITH PASSWORD '$password';

# Create the GitLab production database & grant all privileges on database
template1=# CREATE DATABASE gitlabhq_production OWNER git;

# Quit the database session
template1=# \q

# Try connecting to the new database with the new user
sudo -u git -H psql -d gitlabhq_production

GitLab

Install GitLab into home directory of the user "gitlab"

cd /home/gitlab

Clone from source

Use root to su to gitlab, directly clone and checkout if you are behind firewall, because you may have to explicitly set proxy environment variables for git clone over HTTPS to work.

4.x

# Clone GitLab repository
sudo -u gitlab -H git clone https://github.com/gitlabhq/gitlabhq.git gitlab

# Go to gitlab dir 
cd /home/gitlab/gitlab

# Checkout to stable release
sudo -u gitlab -H git checkout 4-0-stable

Note: You can change 4-0-stable to master if you want the bleeding edge version, but do so with caution!

5.x and above

# Clone GitLab repository
sudo -u git -H git clone https://github.com/gitlabhq/gitlabhq.git gitlab

# Go to gitlab dir
cd /home/git/gitlab

# Checkout to stable release
sudo -u git -H git checkout 5-4-stable

Configure GitLab

4.x

cd /home/gitlab/gitlab

# Copy the example GitLab config
sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml

# Make sure to change "localhost" to the fully-qualified domain name of your
# host serving GitLab where necessary
sudo -u gitlab -H vim config/gitlab.yml

# Make sure GitLab can write to the log/ and tmp/ directories
sudo chown -R gitlab log/
sudo chown -R gitlab tmp/
sudo chmod -R u+rwX  log/
sudo chmod -R u+rwX  tmp/

# Copy the example Unicorn config
sudo -u gitlab -H cp config/unicorn.rb.example config/unicorn.rb

Important Note: Make sure to edit both files to match your setup.

5.x and abvoe

cd /home/git/gitlab

# Copy the example GitLab config
sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml

# Make sure to change "localhost" to the fully-qualified domain name of your
# host serving GitLab where necessary
sudo -u git -H editor config/gitlab.yml

# Make sure GitLab can write to the log/ and tmp/ directories
sudo chown -R git log/
sudo chown -R git tmp/
sudo chmod -R u+rwX  log/
sudo chmod -R u+rwX  tmp/

# Create directory for satellites
sudo -u git -H mkdir /home/git/gitlab-satellites

# Create directories for sockets/pids and make sure GitLab can write to them
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/

# Create public/uploads directory otherwise backup will fail
sudo -u git -H mkdir public/uploads
sudo chmod -R u+rwX  public/uploads

# Copy the example Puma config
sudo -u git -H cp config/puma.rb.example config/puma.rb

# Enable cluster mode if you expect to have a high load instance
# Ex. change amount of workers to 3 for 2GB RAM server
sudo -u git -H editor config/puma.rb

# Configure Git global settings for git user, useful when editing via web
# Edit user.email according to what is set in gitlab.yml
sudo -u git -H git config --global user.name "GitLab"
sudo -u git -H git config --global user.email "gitlab@localhost"

Important Note: Make sure to edit both gitlab.yml and puma.rb to match your setup.

Config GitLab Database Settings

4.x

# Mysql
sudo -u gitlab cp config/database.yml.mysql config/database.yml

# PostgreSQL
sudo -u gitlab cp config/database.yml.postgresql config/database.yml

Make sure to update username/password in config/database.yml.

5.x and above

# Mysql
sudo -u git cp config/database.yml.mysql config/database.yml

# PostgreSQL
sudo -u git cp config/database.yml.postgresql config/database.yml

# Make sure to update username/password in config/database.yml.
# You only need to adapt the production settings (first part).
# If you followed the database guide then please do as follows:
# Change 'root' to 'gitlab'
# Change 'secure password' with the value you have given to $password
# You can keep the double quotes around the password
sudo -u git -H editor config/database.yml

# Make config/database.yml readable to git only
sudo -u git -H chmod o-rwx config/database.yml

Install Gems

Install RubyGems

cd /home/gitlab/gitlab
sudo gem install charlock_holmes --version '0.6.9.4'

For MySQL

# 4.x
sudo -u gitlab -H bundle install --deployment --without development test postgres
# 5.x
# For MySQL (note, the option says "without ... postgres")
sudo -u git -H bundle install --deployment --without development test postgres unicorn aws

NOTE: "--withou development test postgres" is to exclude unnecessary gems, not install postgres gem for mysql, pay attention.

For PostgreSQL

# 4.x
sudo -u gitlab -H bundle install --deployment --without development test mysql
# 5.x
# Or for PostgreSQL (note, the option says "without ... mysql")
sudo -u git -H bundle install --deployment --without development test mysql unicorn aws

IMPORTANT: Install libmysqlclient-dev package on ubuntu, otherwise installing mysql2 gem will fail!!!

Configure Git

GitLab needs to be able to commit and push changes to Gitolite. In order to do that Git requires a username and email. (We recommend using the same address used for the email.from setting in config/gitlab.yml)

sudo -u gitlab -H git config --global user.name "GitLab"
sudo -u gitlab -H git config --global user.email "gitlab@localhost"

Setup GitLab Hooks (4.x ONLY)

sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
sudo chown git:git /home/git/.gitolite/hooks/common/post-receive

Initialize Database and Activate Advanced Features

sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production

Check Application Status

Check if GitLab and its environment is configured correctly

sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production

To make sure you didn't miss anything run a more thorough check with

sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production

If all items are green, then congratulations on successfully installing GitLab! However there are still a few steps left.

Install Init Script

Download the init script (will be /etc/init.d/gitlab)

# sudo wget -c -S --no-check-certificate https://raw.github.com/gitlabhq/gitlab-recipes/4-0-stable/init.d/gitlab -O /etc/init.d/gitlab
sudo curl -o /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/4-0-stable/init.d/gitlab -k
sudo chmod +x /etc/init.d/gitlab

NOTE: make sure to change version 4-0-stable to the version you want.

Start GitLab on boot

sudo update-rc.d gitlab defaults 21

Start GitLab instance

sudo service gitlab start
# or
sudo /etc/init.d/gitlab restart

Nginx

Installation

For latest stable version, check Ningx)

apt-get install nginx

Site Configuration

Download an example site config

# 4.x
# sudo wget --no-check-certificate https://raw.github.com/gitlabhq/gitlab-recipes/master/nginx/gitlab -P /etc/nginx/sites-available/
sudo wget --no-check-certificate https://raw.github.com/gitlabhq/gitlab-recipes/master/nginx/gitlab -O /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab
 
# 5.x
sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab

Make sure to edit the config file to match your setup

# Change **YOUR_SERVER_IP** and **YOUR_SERVER_FQDN**
# to the IP address and fully-qualified domain name
# of your host serving GitLab
sudo vim /etc/nginx/sites-enabled/gitlab

Add Nginx user to git group

nginx user needs to be added to git group so as to gain access (read/execute) to the assets under /home/git/gitlab/public folder. If NOT correctly set, when accessing GitLab users will see a broken page with no assets (images, JavaScript, CSS files) loaded. In nginx error log, permission denied error will be seen because nginx user (www-data in this case) is not a member of git group.

NOTE: In the installation guide, adding Nginx user to the git group is NOT explicitly mentioned. However, it is documented in the Gitlab Recipes (Unofficial production installations).

Recommended workaround

add nginx user to git group and give groups read/execute permission on /home/git

sudo usermod -a -G git www-data
sudo chmod g+rx /home/git/

Alternatively, replace the default nginx user with git and group root in /etc/nginx/nginx.conf

# user www-data;
user git root;

Then restart Nginx, the issue should be fixed.

Restart Nginx

sudo /etc/init.d/nginx restart

Try out GitLab

DONE!

Visit your server for your first GitLab login. The setup has created an admin account for you. You can use it to log in

admin@local.host
5iveL!fe

Important Note: Please go over to your profile page and immediately change the password, so nobody can access your GitLab by using this login information later on.

Enjoy!

Update from a previous version

From 4.0 to 4.1

Important changes

Resque replaced with Sidekiq
New options for configuration file added
Init.d script should be updated

Stop gitlab service

stop running gitlab

sudo service gitlab stop

Update GitLab

Get latest code

sudo -u gitlab -H git pull
sudo -u gitlab -H git checkout 4-1-stable

NOTE: if the machine is behind firewall and require proxy to access the Internet, su to gitlab and set up environment variables properly and do git fetch and git checkout from the gitlab home directly.

NOTE: git pull combines git fetch and git merge. Official upgrade guide recommends using git fetch, after that you have to manually merge.

Install gems for MySQL

sudo -u gitlab -H bundle install --without development test postgres

Migrate Database

sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production

Example output

$ bundle exec rake db:migrate RAILS_ENV=production
==  RenameOwnerToCreatorForProject: migrating =================================
-- rename_column(:projects, :owner_id, :creator_id)
   -> 0.6835s
==  RenameOwnerToCreatorForProject: migrated (0.6842s) ========================
==  AddPublicToProject: migrating =============================================
-- add_column(:projects, :public, :boolean, {:default=>false, :null=>false})
   -> 0.0426s
==  AddPublicToProject: migrated (0.0431s) ====================================

Update the post-receive hook manually

sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive
sudo chown git:git /home/git/.gitolite/hooks/common/post-receive

Replace the init.d script with the new one

# backup old one
sudo mv /etc/init.d/gitlab /etc/init.d/gitlab.old

# get new one usign sidekiq
sudo curl --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/4-1-stable/init.d/gitlab
sudo chmod +x /etc/init.d/gitlab

Check GitLab status

sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production

Start GitLab and Sidekiq

sudo service gitlab start

Remove the old init.d script

sudo rm /etc/init.d/gitlab.old

Update Gitolite

https://github.com/gitlabhq/gitlabhq/wiki/Update-Gitolite

Tips

Cleans up unused gems in the bundler directory

cd /home/git/gitlab
bundle clean

NOTE: Removes unused, outdated gems from /home/git/gitlab/vendor/bundle/ruby/1.9.1/gems to save disk space.

Reference

Troubleshooting Guide

GitLab @ GitHub