From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

This guide is a rough port from the official guide and various internet references.

Some of the steps have been consolidated and obviously customized to the standard Gentoo environment.

If something is missing, please make a point of updating this article, with special attention to dependencies please.

This is a long installation guide, an alternative would be to use the unofficial www-apps/gitlab-ce ebuild from Fritteli’s Overlay.

The Layman's guide

The Gitlab overlay, originally the CVUT overlay, is currently on par with the latest gitlab version (7.12 as of June 2015). It supports gitlab migrations in a post-configure step, for those performing upgrades. The repo and issues can be found here.

Fritteli's Gentoo overlay provides an alternative, though the installation instructions are not documented here.

The overlay may be added using either eselect repository or layman.

To add using eselect repository:

root #eselect repository enable gitlab
root #emerge --sync gitlab

To add using layman:

root #layman -a gitlab

One must then add the following keywords to be accepted by Portage

root #nano /etc/portage/package.accept_keywords.
=app-eselect/eselect-gitlabhq-M.m.i ~ARCH
=dev-libs/libuv-M.m.i ~ARCH
=dev-ruby/bundler-M.m.i ~ARCH
=dev-ruby/rake-M.m.i ~ARCH
=dev-ruby/redis-M.m.i ~ARCH
=dev-vcs/gitlab-gitaly-M.m.i ~ARCH
=dev-vcs/gitlab-shell-M.m.i ~ARCH
=net-libs/http-parser-M.m.i ~ARCH
=net-libs/nodejs-M.m.i ~ARCH
=sys-apps/yarn-M.m.i ~ARCH
=www-apps/gitlabhq-M.m.i ~ARCH
=www-servers/gitlab-workhorse-M.m.i ~ARCH

Where ARCH is the architecture and M.m.i are the Major, minor and intermittent/incremental version numbers.

Setup a git user with a home directory, then export it into an environmental variable. The git user will also need to be part of the 'redis' group. This is important later on as the configuration script needs access to /var/run/redis/redis.sock

root #useradd -m git -g git -G redis
root #export GIT_HOME=/home/git

Next emerge the package. You will also need the newest version of bundler, redis and rake for redis to work correctly.

root #emerge -av gitlabhq
root #emerge -auv bundler rake dev-ruby/redis
The unicorn.rb file is not mentioned in these instructions but it too resides in /etc/gitlabhq-M.m/ and must be created and modified from it's corresponding .example file.

For some reason, the gitlabhq package doesn't user bundler to install sidekiq and unicorn-rails. You can install them through using gem. Sidekiq is needed for redis to work correctly, unicorn-rails is needed for gitlabhq.

root #gem install sidekiq unicorn-rails

Next, create all required configuration files from example configs (if they don't exist):

root #cp /etc/gitlabhq-10.5/config/database.yml.mysql /etc/gitlabhq-10.5/database.yml
root #cp /etc/gitlabhq-10.5/config/gitlab.yml.example /etc/gitlabhq-10.5/gitlab.yml
root #cp /etc/gitlabhq-10.5/config/resque.yml.example /etc/gitlabhq-10.5/resque.yml
root #cp /etc/gitlabhq-10.5/config/unicorn.yml.example /etc/gitlabhq-10.5/unicorn.yml
root #cp /var/lib/gitlab-shell/config.yml.example /var/lib/gitlab-shell/config.yml

If intending to use PostgreSQL:

root #cp /etc/gitlabhq-10.5/config/database.yml.postgresql /etc/gitlabhq-10.5/database.yml

It may be desirable to create a sidekiq config:

FILE /etc/gitlabhq-10.5/sidekiq.yml
# Sample configuration file for Sidekiq.
# Options here can still be overridden by cmd line args.
# Place this file at config/sidekiq.yml and Sidekiq will
# pick it up automatically.

:verbose: false
:concurrency: 20

# Set timeout to 8 on Heroku, longer if managing systems under administrative control.
:timeout: 30

# Sidekiq will run this file through ERB when reading it so it is possible to
# put in dynamic logic, like a host-specific queue.
  - critical
  - default
  - <%= `hostname`.strip %>
  - low

# it is possible to override concurrency based on environment
  :concurrency: 20
  :concurrency: 20

Default owners are incorrect.

root #chown -R git:git /opt/gitlabhq-10.5
root #chown -R git:git /etc/gitlabhq-10.5
root #chown -R git:git /var/lib/gitlab-shell

Then change some values in Gitlab-shell config. By default, user git is supposed to have a home directory (/home/git), but gitlab.yml expects it to have a home in /var/lib/git. It has to be fixed:

git ~/nano /var/lib/gitlab-shell/config.yml

Change all occurrences of var/lib/git/ to /home/git.

FILE /var/lib/gitlab-shell/config.yml
#repos_path: "/var/lib/git/repositories"
repos_path: "/home/git/repositories"
#auth_file: "/var/lib/git/.ssh/authorized_keys"
auth_file: "/home/git/.ssh/authorized_keys"

Now you need to configure redis to have a UNIX socket.

FILE /etc/redis.conf
unixsocket /var/run/redis/redis.sock
unixsocketperm 770

Restart redis.

root #/etc/init.d/redis restart

Assuming you're using Postgresql and have it configured, the gitlabhq configuration script expects a ROLE with the username of git, a password of 'gitlab', LOGIN, CREATEDB and SUPERUSER privileges.

root #psql -U postgres -c "CREATE ROLE git PASSWORD 'gitlab' LOGIN CREATEDB SUPERUSER;"

Finally you can run the configuration script.

root #emerge --config gitlabhq

Now you can start the gitlabhq service:

root #/etc/init.d/gitlabhq-10.5 start

Otherwise for a more Gentoo-ish approach to installation read on.

Prerequisites and dependencies

root #echo "dev-lang/tk threads" >> /etc/portage/package.use
root #emerge --ask dev-libs/openssl dev-libs/icu dev-lang/ruby dev-vcs/git dev-db/redis app-admin/sudo

Optional: To receive mailing notifications from GitLab, install a mail server. The recommended server is Postfix.

root #emerge --ask mail-mta/postfix

Next, tell Gentoo to start redis automagically:

root #rc-update add redis default
root #rc-service redis start

Prepare the necessary users

root #eselect ruby set ruby20
root #eselect python set python2.7

Gitlab uses the git user, so add it:

root #useradd -m -s /bin/bash -c 'Git Version Control' -d /home/git git

echo 'export PATH=$(ruby -rubygems -e "puts Gem.user_dir")/bin:/usr/local/bin:$PATH' >> /home/git/.bashrc

Gitlab shell

root #cd /home/git
root #sudo -u git -H git clone -b v1.9.3 && cd gitlab-shell
git ~/gitlab-shellcp config.yml.example config.yml
Edit config.yml with the domain information or "localhost"
git ~/gitlab-shellnano config.yml
git ~/gitlab-shell./bin/install
If no commit messages are visible in gitlab or there are no error messages while pushing commits to gitlab. If using the unix socket to connect to redis service then also remember to set the redis.sock permissions.
remote: GitLab: An unexpected error occurred (redis-cli returned 1).
git ~/gitlab-shellusermod -aG redis git
git ~/gitlab-shellnano /etc/redis.conf
unixsocket /var/run/redis/redis.sock
unixsocketperm 770


root #su git
git $cd
git ~ $git clone gitlab
git ~ $cd gitlab
git ~/gitlab $git checkout 6-3-stable

Prepare the database


Merge mysql if it has not been done so already.

root #emerge --ask mysql

Setup root mysql password.

The config version will probably be different, read emerge output to get the exact command to run
root #emerge --config =dev-db/mysql-5.1.67

Turn on mysql.

root #rc-service mysql start

Set mysql to start upon reboot.

root #rc-update add mysql default

Create the database and user:

set required passwords for lines 2 and 3
root #mysql -u root -p
mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
mysql> CREATE USER 'gitlab'@'localhost' IDENTIFIED BY 'changeme aka gitlabdbpass';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON `gitlabhq_production`.* TO 'gitlab'@'localhost' IDENTIFIED BY 'gitlabdbpass';
mysql> quit

Test connecting to the databases with the new user:

root #mysql -u gitlab -p -D gitlabhq_production
Enter Password:
git /home/git/gitlab $cp config/database.yml.mysql config/database.yml
git /home/git/gitlab $nano config/database.yml
add the database password to this config file
root /home/git/gitlab $chmod o-rwx config/database.yml


When emerging PostgreSQL, USE="server" is only needed when running the server on the same host as GitLab.

root #emerge --ask dev-db/postgresql

For PostgreSQL there are different methods of authentication. For a installation on the local machine some administrators prefer using the local account when connecting through a socket. By default this is enabled.

Create a new user for GitLab to use when connecting, and create a database for with the new user as the owner. A password isn't strictly necessary, but is good practice. You'll need

user $createuser -P -U postgres -h hostname gitlab
user $createdb -U postgres -h hostname -O git gitlabhq_production

And a little test, just to be sure everything went fine:

git /home/git/gitlab $psql -l

Copy the example database configuration file:

git /home/git/gitlab $cp config/database.yml.postgresql config/database.yml

Edit the new configuration file and add the database credentials just created:

git /home/git/gitlab $nano config/database.yml
  adapter: postgresql
  encoding: unicode
  database: gitlabhq_production
  pool: 5
  username: gitlab
  password: password
  # host: localhost
  # port: 5432
  # socket: /run/postgresql/.s.PGSQL.5432
root /home/git/gitlab #chmod o-rwx config/database.yml

Configure Gitlab

git ~/gitlab $cp config/gitlab.yml.example config/gitlab.yml
edit this file with the domain name (or localhost) & edit the email sent from settings
git ~/gitlab $nano config/gitlab.yml

Deploy directories

root /home/git/gitlab $
chown -R git log/
chown -R git tmp/
chmod -R u+rwX  log/
chmod -R u+rwX  tmp/
git ~/gitlab $
mkdir /home/git/gitlab-satellites
mkdir tmp/pids/
mkdir tmp/sockets/
mkdir public/uploads
cp config/unicorn.rb.example config/unicorn.rb
nano config/unicorn.rb
cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
nano config/initializers/rack_attack.rb
git config --global "GitLab"
git config --global "gitlab@localhost"
git config --global core.autocrlf input
add workers for higher loads and higher ram counts 3 for 2GB is default example
root /home/git/gitlab #chmod -R u+rwX tmp/pids/
root /home/git/gitlab #chmod -R u+rwX tmp/sockets/
root /home/git/gitlab #chmod -R u+rwX public/uploads

Install needed gems

Note that charlock_holmes has a bug on gentoo, so a workaround is required:

git /home/git/gitlab $bundle config build.charlock_holmes --with-ldflags='-L. -Wl,-O1 -Wl,--as-needed -rdynamic -Wl,-export-dynamic'

Note that there might be an error message about a dropped dependency called "modernizr". This is a frontend gem who has been renamed. This has to be added to the Gemfile:

git /home/git/gitlabnano Gemfile

just search the modernizr (v. 2.6.2) package and rename it to "modernizr-rails", "2.7.1". Also Note that a (maybe failing) command, being issued before, has created a Gemfile.lock. This lock file would need an edit as well (two mentions of modernizr).

Then build the package depending on the database setup, excluding the staging and dev environment (which have not been set up yet) and the not-used database:

  • mysql
git /home/git/gitlab $bundle install --deployment --without development test mysql
  • postgresql
git /home/git/gitlab $bundle install --deployment --without development test postgres
If there are problems installing because of Github's SSL cert, use export GIT_SSL_NO_VERIFY=true

Initialize database and activate advanced features

git /home/git/gitlab $bundle exec rake gitlab:setup RAILS_ENV=production
Config files seems to be indentation sensitive, so check the files for typos.

Download and start the initscript

At the time of writing, this init script is confirmed to work with Gitlab versions 6, just edit the user and home directory:

root #chmod +x /etc/init.d/gitlab
root #/etc/init.d/gitlab start
root #rc-update add gitlab default

Web frontend


Download the official template and activate it:

root #wget -O /etc/nginx/sites-available/git.domain.tld
root #ln -s /etc/nginx/sites-available/git.domain.tld /etc/nginx/sites-enabled/

Use a favorite text editor to change the relevant portions:

root #nano /etc/nginx/sites-available/git.domain.tld
  listen default_server;
  server_name git.domain.tld;
root #/etc/init.d/nginx restart


go over to the rails page, and fix up passenger...

The /etc/apache2/vhosts.d/00_default_vhost.conf file needs to be edited, to adapt DocumentRoot and <Directory> directives to use /home/gitlab/gitlab/public. Thus, add the following virtual host to manage gitlab :

root #mv /etc/apache2/vhosts.d/00_default_vhost.conf /etc/apache2/vhosts.d/00_default_vhost.conf.example
FILE /etc/apache2/vhosts.d/00_default_vhost.conf
Listen 80
NameVirtualHost *:80
<VirtualHost *:80>
        DocumentRoot /home/git/gitlab/public
        <Directory /home/git/gitlab/public>

Now apache has to be restarted, don't forget to

root #/etc/init.d/apache2 restart
root #rc-update add apache2 default

Finish installing

To remove login for the git user (Optional), use this:

root #usermod -s /sbin/nologin git
To get the login back later, use usermod -s /bin/bash git

Then build the assets for the Web Frontend using:

git /home/git/gitlab#bundle exec rake assets:precompile RAILS_ENV=production
This step is important. Missing out on it would most likely land you with timeout errors, to resolve which, you will need to increase timeouts of servers to 300-600s. Better precompile manually.

Use a favorite web browser to navigate to the new host that was set up
If everything loads properly, the installer has made an admin account.

Fresh combination




Run this command to get a full diagnostic.

git /home/git/gitlab#bundle exec rake gitlab:env:info RAILS_ENV=production
git /home/git/gitlab#bundle exec rake gitlab:check RAILS_ENV=production

Push, pull, clone

Users to push, pull, clone generate ssh-rsa key.

Using the GitLab web page interface, add a user key to a user, & create new repository.

Many commands will show up, they need to be run on the users computer.

The command 'git push -u origin master' will activate the repository created and allow cloning.

clone using the url the web interface displays. (replace localhost with IP address, or fully qualified domain name)

user $git clone git@localhost:user/test.git test


In the file /home/gitlab/gitlab/config/gitlab.yml there's a section that controls login from remote sites such as Google, Twitter, and GitHub. change enabled: false to enabled: true. then scroll down and remove all ## marks from

FILE /home/gitlab/gitlab/config/gitlab.yml
#    - { name: 'google_oauth2', app_id: 'YOUR APP ID',
#        app_secret: 'YOUR APP SECRET',

and ensure to leave the leading - on the first line.