How to Install GitLab on Debian: Complete Step‑by‑Step Guide

Installation Overview

GitLab installation involves configuring the following components:

Install packages and resolve dependencies

Ruby environment

Go

System user

Database (MySQL/PostgreSQL)

Redis

GitLab‑CE

Nginx

1. Install Packages and Resolve Dependencies

Debian does not include sudo by default. Update the system and install sudo first.

#run as root!
apt-get update -y
apt-get upgrade -y
apt-get install sudo -y

1.1 Install essential system packages

sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl openssh-server redis-server checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libicu-dev logrotate python-docutils pkg-config cmake nodejs

If Kerberos authentication is needed, also install libkrb5-dev:

sudo apt-get install libkrb5-dev

If you are not using Kerberos, you can skip the libkrb5-dev installation.

1.2 Install Git

# Install Git
sudo apt-get install -y git-core
# Verify version (must be >= 1.7.10)
git --version

If the repository version is too old, remove it and compile the latest version from source:

# Remove old Git
sudo apt-get remove git-core
# Install build dependencies
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential
# Download and compile source
cd /tmp
curl -L --progress https://www.kernel.org/pub/software/scm/git/git-2.4.3.tar.gz | tar xz
cd git-2.4.3/
./configure
make prefix=/usr/local all
sudo make prefix=/usr/local install
# Update gitlab.yml later to point to /usr/local/bin/git

GitLab needs a mail service for notifications. Debian includes Exim4; on Ubuntu you should install Postfix:

sudo apt-get install -y postfix

Choose "Internet Site" and confirm the hostname.

2. Ruby Environment

Using RVM, rbenv or chruby often causes issues with GitLab‑Shell. It is recommended to install Ruby manually.

Remove any existing Ruby 1.8 first: sudo apt-get remove ruby1.8 Download and compile Ruby from source:

mkdir /tmp/ruby && cd /tmp/ruby
curl -O --progress http://mirrors.ustc.edu.cn/ruby/2.2/ruby-2.2.2.tar.gz
tar xzf ruby-2.2.2.tar.gz
cd ruby-2.2.2
./configure --disable-install-rdoc
make
sudo make install

Configure Gem sources for China:

# Switch to Taobao mirror
sudo gem sources --add https://gems.ruby-china.org/ --remove https://rubygems.org/
sudo gem sources -l
# Install Bundler
sudo gem install bundler --no-ri --no-rdoc
# Point Bundler to the mirror
sudo -u git -H bundle config mirror.https://rubygems.org https://gems.ruby-china.org/

3. Go

GitLab 8.0+ uses gitlab-git-http-server written in Go. Install the Go compiler:

$ mkdir /tmp/go && cd /tmp/go
$ curl -O --progress http://www.golangtc.com/static/go/go1.5.1/go1.5.1.linux-amd64.tar.gz
$ echo '46eecd290d8803887dec718c691cc243f2175fe0  go1.5.1.linux-amd64.tar.gz' | shasum -c - && \
    sudo tar -C /usr/local -xzf go1.5.1.linux-amd64.tar.gz
$ sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/
$ rm go1.5.1.linux-amd64.tar.gz

4. Create System User

Create a dedicated git user for GitLab:

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

5. Database

GitLab recommends PostgreSQL; MySQL is also supported.

PostgreSQL version must be at least 9.1 for some extensions.

# Install PostgreSQL packages
sudo apt-get install -y postgresql postgresql-client libpq-dev
# Switch to the postgres user and create a GitLab role and database
sudo -u postgres psql -d template1
template1=# CREATE USER git CREATEDB;
template1=# CREATE DATABASE gitlabhq_production OWNER git;
template1=# \q
# Test connection as git user
sudo -u git -H psql -d gitlabhq_production
gitlabhq_production=> \q

6. Redis

sudo apt-get install redis-server
# Configure Redis to use a Unix socket
sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig
sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf
echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf
echo 'unixsocketperm 770' | sudo tee -a /etc/redis/redis.conf
mkdir /var/run/redis
sudo chown redis:redis /var/run/redis
sudo chmod 755 /var/run/redis
# Persist socket directory if /etc/tmpfiles.d exists
if [ -d /etc/tmpfiles.d ]; then
  echo 'd  /var/run/redis  0755  redis  redis  10d  -' | sudo tee -a /etc/tmpfiles.d/redis.conf
fi
sudo service redis-server restart
# Add git user to redis group
sudo usermod -aG redis git

7. GitLab (Core Installation)

# Switch to git user's home
cd /home/git
# Clone GitLab CE source (stable branch)
sudo -u git -H git clone https://git.oschina.net/qiai365/gitlab-ce.git -b 8-1-stable gitlab

Configure GitLab:

# Enter the source directory
cd /home/git/gitlab
# Copy example configuration files
sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml
sudo -u git -H cp config/secrets.yml.example config/secrets.yml
sudo -u git -H chmod 0600 config/secrets.yml
# Adjust permissions for logs and tmp
sudo chown -R git log/ tmp/
sudo chmod -R u+rwX,go-w log/ tmp/
# Create required directories
sudo -u git -H mkdir -p public/uploads builds
sudo -u git -H chmod -R u+rwX public/uploads builds
# Copy Unicorn and Rack‑Attack configs
sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb
sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
# Set global Git config for the git user
sudo -u git -H git config --global core.autocrlf input
# Configure Redis options for GitLab
sudo -u git -H cp config/resque.yml.example config/resque.yml
# Edit gitlab.yml and unicorn.rb to match your environment

Important: adjust gitlab.yml and unicorn.rb according to your own setup.

Configure database settings (PostgreSQL example):

sudo -u git cp config/database.yml.postgresql config/database.yml
sudo -u git -H editor config/database.yml
sudo -u git -H chmod o-rwx config/database.yml

Install required Gems:

# PostgreSQL environment
sudo -u git -H bundle install --deployment --without development test mysql aws kerberos
# MySQL environment
sudo -u git -H bundle install --deployment --without development test postgres aws kerberos

From Bundler 1.5.2 you can speed up installation with bundle install -j$(nproc) .

Install GitLab Shell:

# Install gitlab-shell (adjust REDIS_URL if needed)
sudo -u git -H bundle exec rake gitlab:shell:install[v2.6.6] REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production
# Verify or edit /home/git/gitlab-shell/config.yml if necessary

Install gitlab‑git‑http‑server:

cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-git-http-server.git
cd gitlab-git-http-server
sudo -u git -H git checkout 0.3.0
sudo -u git -H make

Initialize the database and create the admin account:

# Run setup
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
# When prompted, type 'yes' to create the database tables.
# The setup will display the default admin credentials:
# login: root
# password: 5iveL!fe
# You can set a custom password via GITLAB_ROOT_PASSWORD environment variable:
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword

Secure secrets.yml (back up separately from database backups).

Install init script and enable auto‑start:

sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
sudo update-rc.d gitlab defaults 21

Configure log rotation:

sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab

Check the installation status:

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

Pre‑compile assets:

sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production

Start GitLab:

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