Distribution : CentOS 6.4
GitLab version : 5.4
Web Server : Apache
Init system : sysvinit
Database : mysql
Contributors : @nielsbasjes, @axilleas, @mairin
Additional Notes : In order to get the latest git version we build it from source
Overview
Please read doc/install/requirements.md for hardware and platform requirements.
This guide installs GitLab on a bare system from scratch, using MySQL as the database. All Postgres installation steps are absent as they have not been tested yet. Pull requests with tested Postgres are welcome!
Important Notes
The following steps have been known to work. If you deviate from this guide, do it with caution and make sure you don't violate any assumptions GitLab makes about its environment. We have also tried this on RHEL 6.3 and found that there are subtle differences which are documented in part. Look for the RHEL Notes note.
If you find a bug
If you find a bug/error in this guide please submit an issue or pull request
following the contribution guide (see ../../contributing.md).
Security
Many setup guides of Linux software simply state: "disable selinux and firewall". This guide does not disable any of them, we simply configure them as they were intended.
The GitLab installation consists of setting up the following components:
- Installing the base operating system (CentOS 6.4 Minimal) and Packages / Dependencies
- Ruby
- System Users
- GitLab shell
- Database
- GitLab
- Web server
1. Installing the operating system (CentOS 6.4 Minimal)
We start with a completely clean CentOS 6.4 "minimal" installation which can be accomplished by downloading the appropriate installation iso file. Just boot the system of the iso file and install the system.
Note that during the installation you use the "Configure Network" option (it's a button in the same screen where you specify the hostname) to enable the "Connect automatically" option for the network interface and hand (usually eth0).
If you forget this option the network will NOT start at boot.
The end result is a bare minimum CentOS installation that effectively only has network connectivity and (almost) no services at all.
Updating and adding basic software and services
Add EPEL repository
EPEL is a volunteer-based community effort from the Fedora project to create a repository of high-quality add-on packages that complement the Fedora-based Red Hat Enterprise Linux (RHEL) and its compatible spinoffs, such as CentOS and Scientific Linux.
As part of the Fedora packaging community, EPEL packages are 100% free/libre open source software (FLOSS).
Download the GPG key for EPEL repository from fedoraproject and install it on your system:
sudo wget -O /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6 https://fedoraproject.org/static/0608B895.txt
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-6
Verify that the key got installed successfully:
sudo rpm -qa gpg*
gpg-pubkey-0608b895-4bd22942
Now install the epel-release-6-8.noarch package, which will enable EPEL repository on your system:
sudo rpm -Uvh http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
Note: Don't mind the x86_64, if you install on a i686 system you can use the same commands.
Verify that the EPEL repository is enabled as shown below. Now, you’ll see epel repository (apart from the standard base, updates and extras repositories):
sudo yum repolist
repo id repo name status
base CentOS-6 - Base 4,802
epel Extra Packages for Enterprise Linux 6 - x86_64 7,879
extras CentOS-6 - Extras 12
updates CentOS-6 - Updates 814
repolist: 13,507
If you can't see it listed, use the folowing command to enable it:
sudo yum-config-manager --enable epel
Install the required tools for GitLab
::bash
su -
yum -y update
yum -y groupinstall 'Development Tools'
### 'Additional Development'
yum -y install vim-enhanced readline readline-devel ncurses-devel gdbm-devel glibc-devel tcl-devel openssl-devel curl-devel expat-devel db4-devel byacc sqlite-devel gcc-c++ libyaml libyaml-devel libffi libffi-devel libxml2 libxml2-devel libxslt libxslt-devel libicu libicu-devel system-config-firewall-tui python-devel redis sudo wget crontabs logwatch logrotate perl-Time-HiRes
RHEL Notes
If some packages (eg. gdbm-devel, libffi-devel and libicu-devel) are NOT installed, add the rhel6 optional packages repo to your server to get those packages:
yum-config-manager --enable rhel-6-server-optional-rpms
Tip taken from here.
Git
GitLab will only work correctly with git version 1.8.x or newer. The problem is that the available rpms for CentOS stop at git 1.7.1 which is too old for GitLab. In order to update, you have to build git from source as it is not yet in any repository:
::bash
su -
cd /tmp
yum -y install git perl-ExtUtils-MakeMaker
git clone git://github.com/git/git.git
cd /tmp/git/
git checkout v1.8.3.4
autoconf
./configure --prefix=/usr/local
make && make install
rm -rf /tmp/git/
yum erase git
Logout and login again for the $PATH to take effect. Check that git is properly
installed with:
which git
# /usr/local/bin/git
git --version
# git version 1.8.3.4
Configure redis
Make sure redis is started on boot:
::bash
sudo chkconfig redis on
Configure sendmail
su -
yum -y install sendmail-cf
cd /etc/mail
vim /etc/mail/sendmail.mc
Add a line with the smtp gateway hostname
define(`SMART_HOST', `smtp.example.com')dnl
Then replace this line:
EXPOSED_USER(`root')dnl
with:
dnl EXPOSED_USER(`root')dnl
Now enable these settings:
make
chkconfig sendmail on
Alternatively you can install postfix.
2. Ruby
Download and compile it:
su -
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 --prefix=/usr/local/
make && make install
Install the Bundler Gem:
sudo gem install bundler
3. System Users
Create user for Git
su -
adduser \
--system \
--shell /bin/bash \
--comment 'Git Version Control' \
--create-home \
--home-dir /home/git \
git
We do NOT set the password so this user cannot login.
Forwarding all emails
Now we want all logging of the system to be forwarded to a central email address:
su -
echo adminlogs@example.com > /root/.forward
chown root /root/.forward
chmod 600 /root/.forward
restorecon /root/.forward
echo adminlogs@example.com > /home/git/.forward
chown git /home/git/.forward
chmod 600 /home/git/.forward
restorecon /home/git/.forward
Configure mysql
Install and enable the mysqld service to start on boot:
::bash
su -
yum install -y mysql-server mysql-devel
chkconfig mysqld on
service mysqld start
Secure MySQL by entering a root password and say "Yes" to all questions:
/usr/bin/mysql_secure_installation
Create a new user and database for GitLab:
# Login to MySQL
mysql -u root -p
# Create a user for GitLab. (change supersecret to a real password)
CREATE USER 'gitlab'@'localhost' IDENTIFIED BY 'supersecret';
# Create the GitLab production database
CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
# Grant the GitLab user necessary permissopns on the table.
GRANT SELECT, LOCK TABLES, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost';
# Quit the database session
\q
Try connecting to the new database with the new user:
mysql -u gitlab -p -D gitlabhq_production
# Quit the database session
\q
4. GitLab shell
GitLab Shell is a ssh access and repository management software developed specially for GitLab.
# Login as git
su - git
logged in as git
# Go to home directory
cd /home/git
# Clone gitlab shell
git clone https://github.com/gitlabhq/gitlab-shell.git
cd gitlab-shell
# switch to right version
git checkout v1.4.0
cp config.yml.example config.yml
# Edit config and replace gitlab_url
# with something like 'http://domain.com/'
vim config.yml
# Do setup
./bin/install
5. GitLab
logged in as git
# We'll install GitLab into home directory of the user "git"
cd /home/git
Clone the Source
# Clone GitLab repository
git clone https://github.com/gitlabhq/gitlabhq.git gitlab
# Go to gitlab dir
cd /home/git/gitlab
# Checkout to stable release
git checkout 5-2-stable
Note:
You can change 5-2-stable to master if you want the bleeding edge version, but
do so with caution!
Configure it
Copy the example GitLab config
cp /home/git/gitlab/config/gitlab.yml{.example,}
Edit the gitlab config to make sure to change "localhost" to the fully-qualified domain name of your host serving GitLab where necessary. Also review the other settings to match your setup.
vim /home/git/gitlab/config/gitlab.yml
logged in as root
# Make sure GitLab can write to the log/ and tmp/ directories
chown -R git /home/git/gitlab/log/
chown -R git /home/git/gitlab/tmp/
chmod -R u+rwX /home/git/gitlab/log/
chmod -R u+rwX /home/git/gitlab/tmp/
logged in as git
# Create directory for satellites
mkdir /home/git/gitlab-satellites
# Create directories for sockets/pids and make sure GitLab can write to them
mkdir /home/git/gitlab/tmp/pids/
mkdir /home/git/gitlab/tmp/sockets/
chmod -R u+rwX /home/git/gitlab/tmp/pids/
chmod -R u+rwX /home/git/gitlab/tmp/sockets/
# Create public/uploads directory otherwise backup will fail
mkdir /home/git/gitlab/public/uploads
chmod -R u+rwX /home/git/gitlab/public/uploads
# Copy the example Puma config
cp /home/git/gitlab/config/puma.rb{.example,}
# Configure Git global settings for git user, useful when editing via web
# Edit user.email according to what is set in gitlab.yml
git config --global user.name "GitLab"
git config --global user.email "gitlab@localhost"
Important Note:
Make sure to edit both gitlab.yml and puma.rb to match your setup.
Specifically for our setup behind Apache edit the puma config
vim /home/git/gitlab/config/puma.rb
Change the bind parameter so that it reads:
bind 'tcp://127.0.0.1:9292'
Configure GitLab DB settings
# MySQL
cp /home/git/gitlab/config/database.yml{.mysql,}
Edit the database config and set the correct username/password
vim /home/git/gitlab/config/database.yml
The config should look something like this (where supersecret is replaced with your real password):
production:
adapter: mysql2
encoding: utf8
reconnect: false
database: gitlabhq_production
pool: 5
username: gitlab
password: supersecret
# host: localhost
# socket: /tmp/mysql.sock
Install Gems
logged in as git
logout
logged in as root
cd /home/git/gitlab
gem install charlock_holmes --version '0.6.9.4'
su - git
logged in as git
cd /home/git/gitlab
# For mysql db
bundle install --deployment --without development test postgres
Initialize Database and Activate Advanced Features
logged in as git
cd /home/git/gitlab
bundle exec rake gitlab:setup RAILS_ENV=production
Install Init Script
Download the init script (will be /etc/init.d/gitlab)
logged in as git
logout
logged in as root
Double check the url for this next one!!
curl https://raw.github.com/gitlabhq/gitlab-recipes/master/init/sysvinit/centos/gitlab-centos > /etc/init.d/gitlab
chmod +x /etc/init.d/gitlab
chkconfig --add gitlab
Make GitLab start on boot:
chkconfig gitlab on
Start your GitLab instance:
service gitlab start
# or
/etc/init.d/gitlab start
Configure the web server
For nginx:
sudo yum -y install nginx
For Apache:
sudo yum -y install httpd
sudo chkconfig httpd on
sudo wget -O /etc/httpd/conf.d/gitlab.conf https://raw.github.com/gitlabhq/gitlab-recipes/web-server/apache/gitlab
Open /etc/httpd/conf.d/gitlab.conf with your editor and replace git.example.org with your FQDN.
OPTIONAL: If you want to run other websites on the same system you'll need to
add in /etc/httpd/conf/httpd.conf:
NameVirtualHost *:80
Poke a selinux hole for httpd so it can be in front of GitLab:
setsebool -P httpd_can_network_connect on
Configure firewall
Poke an iptables hole so uses can access the httpd (http and https ports) and ssh. The quick way is to put this in the file called /etc/sysconfig/iptables
# Firewall configuration written by system-config-firewall
# Manual customization of this file is not recommended.
*filter
:INPUT ACCEPT [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p icmp -j ACCEPT
-A INPUT -i lo -j ACCEPT
-A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
-A INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
-A INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-host-prohibited
-A FORWARD -j REJECT --reject-with icmp-host-prohibited
COMMIT
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