Differences between revisions 206 and 394 (spanning 188 versions)
Revision 206 as of 2020-08-13 14:19:45
Size: 17739
Editor: Praveen A
Comment: ruby-rack-timeout 0.5.1 is in unstable now and required modules of aws-sdk v3 will be uploaded directly to unstable
Revision 394 as of 2022-09-14 17:15:20
Size: 13226
Editor: Praveen A
Comment: gitlab 15.3.1 is available in staging (waiting for a newer protobuf in experimental)
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
Gitlab is a git front end with repository management, graphs, links, goodies, commands to run, and review capabilities similar in feel to a self-hosted GitHub. 

{{{#!wiki important
New upstream releases (including security updates) are announced at https://about.gitlab.com/releases/categories/releases/.
Gitlab is a git front end with repository management, graphs, links, goodies, commands to run, and review capabilities similar in feel to a self-hosted GitHub.

A new feature release of gitlab flows in the following direction: [[/devel|devel]] -> [[/staging|staging]] -> experimental -> unstable -> [[/fasttrack-staging|fasttrack-staging]] -> fasttrack (experimental and unstable may be skipped during freeze and transitions).

See [[/omnibus]] if you are looking for instructions to install upstream provided packages.


{{{#!wiki important
New upstream releases (including security updates) are announced at https://about.gitlab.com/releases/categories/releases/ and available as RSS feed https://about.gitlab.com/security-releases.xml.
Line 19: Line 23:
== Buster Fast Track (Recommended) ==
Gitlab 13.1.6 is available in [[FastTrack|unofficial fasttrack repo]] targeting buster as base distribution. (no open security issues).


{{{#!wiki important
Some packages are still needed from personal repo of gitlab maintainer because golang packages cannot be uploaded in fasttrack.debian.net because of a [[https://salsa.debian.org/fasttrack-team/support/-/issues/8|bug in dak setup]]. Please note the new URL of this repo if you are upgrading from an older version (people.debian.org/~praveen/gitlab is now people.debian.org/~praveen/gitaly and gpg key used for signing is also changed).
}}}

{{{#!wiki important
Make sure `contrib` section is enabled for `buster` and `buster/updates`
}}}

Modify `/etc/apt/sources.list` to add `contrib` section if missing:
{{{
deb http://deb.debian.org/debian buster main contrib
deb http://security.debian.org/ buster/updates main contrib
}}}

And add the following lines:
{{{
deb https://fasttrack.debian.net/debian/ buster-fasttrack main contrib
{{{#!wiki important
Make sure `contrib` section is enabled for official repos.
}}}

== Story of Gitlab packaging project/FAQ about Gitlab packaging ==

Gitlab Inc sponsored the packaging effort for 6+ years (2016-2022). Currently looking for donations at https://opencollective.com/debian-gitlab.

Though the dependencies are so many, the work benefits Debian immensely by maintaining many important build tools like webpack, rollup, babel, npm, yarn... And frameworks like ruby on rails.

The situation in packaging JavaScript modules is considerably improved over the years thanks to this packaging work. It took over 2 years for packaging handlebars_assets gem for diaspora because its embedded JavaScript library was using tools like gulp, webpack, jison etc and none of this was packaged for Debian. The whole JavaScript build tools were untouched for years in Debian and instead reverse engineering of the build tools for specific libraries was the norm (for example jquery), it was very hard and not scalable.

Out of 1600+ node modules gitlab needs, we have 1200+ modules already packaged. It is not impossible to have it in main (it was in main earlier before the nodejs modules exploded exponentially and if some more people join the team, currently it is mostly a single person work and at times some new people helping out with a handful of dependencies. I don't think it is much harder if you take whole gnome or KDE as comparison. We are able to pull it off because of team work. This project have also brought many new contributors to Debian.

While we might love long term supported releases, calling anything moving fast as insane and not able to adapt to change is a recipe for Debian becoming irrelevant over time. Many just want distros to be only a base os for shipping containers but that is not necessarily a good thing for users to have dependency on a single project for updates and lose choice and flexibility.

We created https://fasttrack.debian.net to serve gitlab as it did not fit into a debian stable release cycle and currently not just gitlab, but matrix synapse and virtual box is also shipped via FastTrack.

== New changes ==
 1. From gitlab 14.7.7: gitlab user needs to write to /var/lib/gitlab/.gem so if you installed gems manually as root user, you will need to update permissions or remove this directory. Gitlab package now installs required unpackaged gems in that directory automatically.
 1. From gitlab 14.2.6: postgresql database should be updated to 13 before installing gitlab 14.2. See [[gitlab/postgresql-update]] for steps to upgrading postgresql to 13.
 1. From gitlab 14.0.10: We no longer require a work around to install grpc and google-protobuf gems from rubygems.org, packaged versions now work.
 1. From 2021 July 23: We no longer require the personal repo of gitlab maintainer to install gitlab, all golang packages can now be added to fasttrack.debian.net directly. Thanks to Akshay S Dinesh for fixing this long pending bug (See https://salsa.debian.org/fasttrack-team/support/-/issues/8 for details).
 1. New workaround from gitlab 13.12.3: You need to use google-protobuf from rubygems.org ([[gitlab#gitlab-sidekiq_service_failure_work_around_.28install_google-protobuf_from_rubygems.org.29|see below for details]]).
 1. New from gitlab 13.10.4: Since this version includes gitlab-workhorse golang binary, it was moved to people.debian.org/~praveen/gitaly and should now include contrib section.
 1. New in gitlab 13.6.7-1: New user created after a fresh installation should be approved using `gitlab-rails-console`. See [[gitlab#your_account_is_awaiting_approval_from_your_GitLab_administrator]] for steps to approving users and creating a user with Administrative privileges.
 1. New in gitlab 13.3.8-1: You will need to install grpc gem from rubygems.org `gem install -v 1.30.2 grpc` (more details below). If you run gitaly on a different machine, you will need to do this on that machine as well.
 1. New in gitlab 13.2.6-3: We have switched to puma as application server replacing unicorn. Upstream already made the switch from 12.9 and unicorn support will be dropped in gitlab 14.0. They saw a memory reduction of 37% in gitlab.com after the switch. See more details about this switch at this upstream blog post https://about.gitlab.com/blog/2020/07/08/migrating-to-puma-on-gitlab/. puma defaults to listening only on unix sockets and if you are running gitaly on a different machine, then you will have to edit `/etc/gitlab/puma.rb` to bind to tcp:// url as well.

== Bullseye FastTrack (Recommended) ==

gitlab 15.3.2 is available in Bullseye FastTrack (no open security issues).

Add fasttrack.debian.net as a trusted repo for apt,
{{{
# apt install fasttrack-archive-keyring ca-certificates
}}}

And add the following lines for fasttrack repo:
{{{
deb https://fasttrack.debian.net/debian/ bullseye-fasttrack main contrib
Line 41: Line 65:
deb https://fasttrack.debian.net/debian/ buster-backports main contrib
deb https://deb.debian.org/debian buster-backports main contrib
# Eventually the packages in this repo will be moved to fasttrack or official backports after fixing https://salsa.debian.org/fasttrack-team/support/-/issues/8
deb https://people.debian.org/~praveen/gitaly buster-backports main

# Optional: To avoid some hours of delay between upload and availability in archive
deb http://incoming.debian.org/debian-buildd buildd-buster-backports main contrib
}}}

Refresh list of available packages:
deb https://fasttrack.debian.net/debian/ bullseye-backports-staging main contrib
}}}

You will also need official bullseye-backports repo:
{{{
deb http://deb.debian.org/debian bullseye-backports main contrib
}}}

Note: You may also use a mirror of fasttrack repo like http://mirror.linux.pizza/debian-fasttrack/

and install gitlab
Line 53: Line 79:
}}}

You may encounter the following error message:
{{{
The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 0B76920762A6B785
}}}

If so, these commands can help (trust these repositories):
{{{
# wget https://people.debian.org/~praveen/gitaly/praveen.key.new.asc
# wget http://fasttrack.debian.net/fasttrack-archive-key.asc
# apt-key add praveen.key.new.asc
# apt-key add fasttrack-archive-key.asc
}}}

{{{#!wiki important
If you are upgrading ruby version to 2.7 (if your current ruby version is 2.5), you will need to use dist-upgrade first. Make sure /var/lib/gems/2.5.0/ is empty if you see any issues after the ruby version upgrade.

See https://git.fosscommunity.in/debian-ruby/TaskTracker/-/issues/166 for current status of ruby 2.7 in fasttrack.
}}}

=== Upgrading along with ruby ===

If you are installing for the first time, skip this section.

''Using apt''
{{{
# apt -t buster-fasttrack dist-upgrade
Reading package lists... Done
Building dependency tree
Reading state information... Done
Calculating upgrade... Done
The following packages were automatically installed and are no longer required:
  libruby2.5 ruby-did-you-mean ruby-trollop ruby2.5-dev ruby2.5-doc
Use 'sudo apt autoremove' to remove them.
The following packages will be REMOVED:
  ruby2.5
The following NEW packages will be installed:
  libruby2.7 ruby-optimist ruby2.7 ruby2.7-dev ruby2.7-doc
The following packages have been kept back:
  gitlab
The following packages will be upgraded:
  apt exim4-base exim4-config exim4-daemon-light libapt-pkg5.0 libdns-export1104 libgrpc9 libisc-export1100 puma ruby
  ruby-atomic ruby-bcrypt ruby-bcrypt-pbkdf ruby-bootsnap ruby-bson ruby-character-set ruby-charlock-holmes
  ruby-commonmarker ruby-concurrent ruby-concurrent-ext ruby-dev ruby-ed25519 ruby-enumerable-statistics
  ruby-escape-utils ruby-fast-blank ruby-ffi ruby-github-linguist ruby-google-protobuf ruby-gpgme ruby-grpc
  ruby-hamlit ruby-hitimes ruby-json ruby-kgio ruby-msgpack ruby-murmurhash3 ruby-nio4r ruby-nokogiri ruby-nokogumbo
  ruby-oj ruby-pg ruby-posix-spawn ruby-prof ruby-prometheus-client-mmap ruby-raindrops ruby-rbtrace ruby-re2
  ruby-redcarpet ruby-redcloth ruby-regexp-property-values ruby-rinku ruby-rugged ruby-sqlite3 ruby-stackprof
  ruby-thrift ruby-timfel-krb5-auth ruby-unf-ext ruby-unicode ruby-version-sorter ruby-vmstat ruby-websocket-driver
  ruby-yajl rubygems-integration unicorn
64 upgraded, 5 newly installed, 1 to remove and 1 not upgraded.
Need to get 20.5 MB of archives.
After this operation, 44.0 MB of additional disk space will be used.
Do you want to continue? [Y/n]
}}}

Now install gitlab:
{{{
# apt -t buster-fasttrack install gitlab
}}}

''Using aptitude''
{{{
# aptitude -t buster-fasttrack dist-upgrade
The following NEW packages will be installed:
  libruby2.7{a} ruby-optimist{a} ruby2.7{a} ruby2.7-dev{a} ruby2.7-doc{a}
The following packages will be REMOVED:
  libruby2.5{u} ruby-did-you-mean{u} ruby-trollop{u} ruby2.5{u} ruby2.5-dev{u} ruby2.5-doc{u}
The following packages will be upgraded:
  apt exim4-base exim4-config exim4-daemon-light gitlab libapt-pkg5.0 libdns-export1104 libgrpc9 libisc-export1100
  puma ruby ruby-atomic ruby-bcrypt ruby-bcrypt-pbkdf ruby-bootsnap ruby-bson ruby-character-set
  ruby-charlock-holmes ruby-commonmarker ruby-concurrent ruby-concurrent-ext ruby-dev ruby-ed25519
  ruby-enumerable-statistics ruby-escape-utils ruby-fast-blank ruby-ffi ruby-github-linguist ruby-google-protobuf
  ruby-gpgme ruby-grpc ruby-hamlit ruby-hitimes ruby-json ruby-kgio ruby-msgpack ruby-murmurhash3 ruby-nio4r
  ruby-nokogiri ruby-nokogumbo ruby-oj ruby-pg ruby-posix-spawn ruby-prof ruby-prometheus-client-mmap
  ruby-raindrops ruby-rbtrace ruby-re2 ruby-redcarpet ruby-redcloth ruby-regexp-property-values ruby-rinku
  ruby-rugged ruby-sqlite3 ruby-stackprof ruby-thrift ruby-timfel-krb5-auth ruby-unf-ext ruby-unicode
  ruby-version-sorter ruby-vmstat ruby-websocket-driver ruby-yajl rubygems-integration unicorn
65 packages upgraded, 5 newly installed, 6 to remove and 0 not upgraded.
Need to get 106 MB of archives. After unpacking 9,644 kB will be used.
Do you want to continue? [Y/n/?]
}}}

=== New installations ===

''Using apt''

At this point, it seems apt cannot resolve the dependencies correctly, see section below to use aptitude or manually specifiy the list of dependencies to install.

{{{
# apt -t buster-fasttrack install puma ruby ruby-atomic ruby-bcrypt \
ruby-bcrypt-pbkdf ruby-bootsnap ruby-bson ruby-character-set \
ruby-charlock-holmes ruby-commonmarker ruby-concurrent ruby-concurrent-ext \
ruby-dev ruby-ed25519 ruby-enumerable-statistics ruby-escape-utils \
ruby-fast-blank ruby-ffi ruby-github-linguist ruby-google-protobuf ruby-gpgme \
ruby-grpc ruby-hitimes ruby-json ruby-kgio ruby-msgpack ruby-murmurhash3 \
ruby-nio4r ruby-nokogiri ruby-nokogumbo ruby-oj ruby-pg ruby-posix-spawn \
ruby-prof ruby-prometheus-client-mmap ruby-raindrops ruby-rbtrace \
ruby-re2 ruby-redcarpet ruby-redcloth ruby-regexp-property-values \
ruby-rinku ruby-rugged ruby-sqlite3 ruby-stackprof ruby-thrift \
ruby-timfel-krb5-auth ruby-unf-ext ruby-unicode ruby-version-sorter \
ruby-vmstat ruby-websocket-driver ruby-yajl rubygems-integration unicorn
}}}

and install gitlab:
{{{
# apt -t buster-backports install gitlab/buster-fasttrack ruby-hamlit/buster-fasttrack
}}}

''Using aptitude''
{{{
# aptitude -t buster-backports install gitlab/buster-fasttrack
}}}

and choose `n` for first choice and then `Y` to prefer packages from fasttrack when it is available in both backports and fasttrack.

{{{#!wiki important
apt priority for buster-fasttrack is lowered to 100 from 500 to match buster-backports settings.
}}}

{{{#!wiki important
We have to use older versions of ruby-grpc as a workaround. See [[DebianBug:966653]] for details.

# apt install ruby-grpc=1.26.0-3+fto10+1

Manually refresh Gemfile.lock as per [[gitlab#manually_installing_ruby_dependencies]]

Another option is to install grpc from rubygems.org (don't forget to remove this version when ruby-grpc is fixed in debian)

# gem install -v 1.30.2 grpc
}}}
''Note: https://gitlab.debian.net is running on this version.''
# apt install gitlab-apt-pin-preferences
# apt install gitlab
}}}
Line 188: Line 84:
Gitlab 12.2.3 is available in unstable but need ruby-aws-sdk from experimental (We will update aws-sdk to v3 directly in unstable, which is in progress, some packages need to clear NEW). See below for installing from experimental.

We try to keep the version in unstable in a good shape with the latest security updates, but some times dependency updates break GitLab.
Gitlab 13.4.7 is available in unstable (many security release behind, see experimental for latest security updates).

We try to keep the version in unstable in a good shape with the latest security updates, but some times dependency updates break gitlab.

Now install gitlab

{{{
# apt install gitlab
}}}

=== Known Issues ===
{{{#!wiki important
Currently gitlab installation is broken due to a change in libsass. See [[DebianBug:953415]] for more details.

A work around is to downgrade libsass and libsass-dev to 3.6.1. Use http://snapshot.debian.org/package/libsass/3.6.1-1/ and hold it at the older version.

# wget http://snapshot.debian.org/archive/debian/20190705T210019Z/pool/main/libs/libsass/libsass-dev_3.6.1-1_amd64.deb

# wget http://snapshot.debian.org/archive/debian/20190705T210019Z/pool/main/libs/libsass/libsass1_3.6.1-1_amd64.deb

# dpkg -i libsass1_3.6.1-1_amd64.deb libsass-dev_3.6.1-1_amd64.deb

# apt-mark hold libsass1 libsass-dev
}}}

{{{#!wiki important
See [[gitlab#gitlab_crash_work_around_.28install_grpc_from_rubygems.org.29]] for installing grpc gem from rubygems.org (just use `apt install ruby2.7` for installing ruby)
}}}

{{{#!wiki important
Downgrade ruby-autoprefixer-rails and node-autoprefixer packages to 10.3.1.0+dfsg1+~cs14.6.19-2 using https://snapshot.debian.org/package/node-autoprefixer/10.3.1.0%2Bdfsg1%2B%7Ecs14.6.19-2/ and hold them to this version.

# apt-mark hold node-autoprefixer ruby-autoprefixer-rails

See [[DebianBug:1009245]]
}}}

{{{#!wiki important
Downgrade ruby-github-linguist till gitaly is adapted to find languages.json from gem-install layout.

Get older version from https://snapshot.debian.org/package/ruby-github-linguist/7.12.2-1/

# apt-mark hold ruby-github-linguist
}}}
Line 194: Line 131:
gitlab 15.2.2 is available in experimental (see below for security fixes).
Line 196: Line 135:
Install ruby-aws-sdk from experimental,

{{{
# apt install git
# apt install ruby-aws-sdk/experimental
}}}

{{{#!wiki important
Currently gitlab installation is broken due to a change in libsass. See [[DebianBug:953415]] for more details.

A work around is to downgrade libsass and libsass-dev to 3.6.1. Use http://snapshot.debian.org/package/libsass/3.6.1-1/
}}}

{{{#!wiki important
Currently gitlab/gitaly crash due to a bug in ruby-grpc. See [[DebianBug:966653]] for more details.

A work around is to downgrade ruby-grpc and install libgrpc9 from http://snapshot.debian.org/package/grpc/1.26.0-3/ (remove libgrpc10 to avoid conflict by running dpkg -r --force-all libgrpc10).

Manually refresh Gemfile.lock as per [[gitlab#manually_installing_ruby_dependencies]]

Another option is to install grpc from rubygems.org (don't forget to remove this version when ruby-grpc is fixed in debian)

# gem install -v 1.30.2 grpc
}}}

{{{#!wiki important
Run rm -rf /var/lib/gitlab/.node_modules/uuid/ and retry installation if you got the following error: error An unexpected error occurred: "Package subpath './v4' is not defined by \"exports\" in "/var/lib/gitlab/.node_modules/uuid/package.json" during "Installing node modules...". See [[DebianBug:964218]] for more details.
}}}

Now install gitlab

{{{
# apt install gitlab
}}}

== Gitlab on Stretch ==

This is moved to [[gitlab/stretch]] now.
{{{#!wiki important
You will have to follow the notes mentioned in unstable section above.
}}}

== Experimental/unstable Staging ==

When gitlab is not ready for official experimental/unstable (for example some dependencies need to clear NEW queue), it will be available from this repo.

gitlab 15.3.1 is available in [[gitlab/staging]]

{{{#!wiki important
You will have to follow the notes mentioned in unstable section above.
}}}

This section moved to [[gitlab/staging]].

== Gitlab on older releases ==

These versions no longer receive any secuity updates and it is recommended to upgrade to Debian 11 Bullseye to continue recieving security updates.

 * [[gitlab/buster|Debian 10 Buster]]
 * [[gitlab/stretch|Debian 9 Stretch]]
Line 238: Line 161:
To get a working configuration for your version the best thing to do is to follow the ([[https://gitlab.com/gitlab-org/gitlab-recipes/-/tree/master/web-server/apache|gitlab-recipes repository]]) instructions.

Basically you will have to :
Disable nginx
Set www-data as web server user.
Allow Modules dependencies
# mod_rewrite
# mod_ssl
# mod_proxy
# mod_proxy_http
# mod_headers

{{{
a2enmod rewrite proxy_http headers
}}}

and as says in recipe

Allow gitlab-workhorse to listen on port 8181, edit or create /etc/default/gitlab and change or add the following:
{{{
 gitlab_workhorse_options="-listenUmask 0 -listenNetwork tcp -listenAddr 127.0.0.1:8181 -authBackend http://127.0.0.1:8080"
}}}


== Gitlab Common Errors ==

If you have this kind of error
{{{
  Cloning into'public-test-project-ssh'...
  Received disconnect from YOUR_SERVER_IP port 22:2: Too many authentication failures
  Disconnected from YOUR_SERVER_IP port 22
  fatal: Can't read distant repository.
}}}
on an ssh clone
{{{
  git clone gitlab@ssh.your-gitlab-instance.org:public-test-group/public-test-project.git public-test-project-ssh
}}}
{{{#!wiki important
Note : In your command line host should match your ssh hostname for gitlab as group and project name.
}}}

To be sure you should find a line like the following in /var/log/auth.log

{{{
User gitlab from YOUR_CLIENT_IP not allowed because not listed in AllowUsers
}}}

You may have to allow gitlab user in /etc/ssh/sshd_config

{{{
AllowUsers user1 user2 gitlab
AllowGroups user1 group2 gitlab
}}}
{{{#!wiki important
Note : user1, user2, group2 are here for the example adapt to your setup.
}}}
Do not forget to restart the service

{{{
service ssh restart
}}}

== Debug installation and configuration ==

Gitlab is composed of several parts. As always logs (/var/log/gitlab), debian specific documentation (/usr/share/doc/gitlab/) and ([[https://docs.gitlab.com/ |official]]) documentation provide lots of information.

`gitlab-rake` is convenience script to easily run rake commands provided by gitlab in debian environment.

{{{
# gitlab-rake gitlab:check
# gitlab-rake gitlab:env:info
}}}

`gitlab-rails-console` is another convenience script to launch a rails console in gitlab debian environment.

{{{
# gitlab-rails-console
}}}

Just make sure you don't have any gems installed from rubygems.org conflicting with debian packaged versions of the gems required by gitlab. `/var/lib/gems/<ruby_version>` (`/var/lib/gems/2.5.0` or `/var/lib/gems/2.7.0`) should not have any gems.

== rake aborted errors during installation ==
If your update failed for some reason (usually when dependencies are not satisfied for `bundle install --local`), and you retry installation after fixing dependencies, you may see errors like
{{{
rake aborted!
NameError: uninitialized constant Gitlab::Patch::ActiveRecordQueryCache
/usr/share/gitlab/config/initializers/active_record_query_cache.rb:3:in `<top (required)>'
}}}

You will have to manually remove problem creating initializers from `/etc/gitlab/initializers`. A list of such initializers can be found from gitlab source package or from https://salsa.debian.org/ruby-team/gitlab in `debian/maintscript` file. All lines starting with `rm_conffile` and corresponding versions are what you need to check.

== manually installing ruby dependencies ==
When ruby dependencies are installed manually, we need to update gitlab and gitaly's Gemfile.lock to use the recently installed version. See [[DebianBug:944698]] for details.

{{{
cd /usr/share/gitlab
truncate -s0 Gemfile.lock
sudo -u gitlab bundle install --local # use the gitlab username instead of gitlab if you changed it
cd /usr/share/gitaly/ruby
truncate -s0 Gemfile.lock
sudo -u gitlab bundle install --local # use the gitlab username instead of gitlab if you changed it
}}}
The ([[https://gitlab.com/gitlab-org/gitlab-recipes/-/tree/master/web-server/apache|gitlab-recipes repository]]) instructions are wrong - apache supports proxying to UNIX sockets so there's no need to change any gitlab configuration to use TCP.

Basically you will have to:
 * disable nginx
 * enable apache modules:
  * mod_rewrite
  * mod_ssl (if needed)
  * mod_proxy
  * mod_proxy_http
  * mod_headers
 * add/modify apache configuration file

{{{
a2enmod rewrite ssl proxy_http headers
}}}

See below for Apache configuration file example (using Let's Encrypt SSL certificates and HTTP to HTTPS redirect). Replace YOUR_SERVER_FQDN string with your domain (e.g. git.example.org).

{{{
<VirtualHost *:80>
 ServerName YOUR_SERVER_FQDN
 Redirect / https://YOUR_SERVER_FQDN/
</VirtualHost>

<VirtualHost *:443>
 SSLCertificateFile /etc/letsencrypt/live/YOUR_SERVER_FQDN/fullchain.pem
 SSLCertificateKeyFile /etc/letsencrypt/live/YOUR_SERVER_FQDN/privkey.pem
 Include /etc/letsencrypt/options-ssl-apache.conf
 Header add Strict-Transport-Security: "max-age=15768000;includeSubdomains"
 ProxyPreserveHost On

 ServerName YOUR_SERVER_FQDN

 # Ensure that encoded slashes are not decoded but left in their encoded state.
 # http://doc.gitlab.com/ce/api/projects.html#get-single-project
 AllowEncodedSlashes NoDecode

 <Location />
  Require all granted
  ProxyPassReverse https://YOUR_SERVER_FQDN/
 </Location>

 RewriteEngine on
 #Forward all requests to gitlab-workhorse except existing files like error documents
 RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR]
 RewriteCond %{REQUEST_URI} ^/uploads/.*
 RewriteRule .* unix:/run/gitlab/gitlab-workhorse.socket|http://YOUR_SERVER_FQDN%{REQUEST_URI} [P,QSA,NE]

 RequestHeader set X_FORWARDED_PROTO 'https'
 RequestHeader set X-Forwarded-Ssl on

 # needed for downloading attachments
 DocumentRoot /var/lib/gitlab/public

 # Set up apache error documents, if back end goes down (i.e. 503 error) then a maintenance/deploy page is thrown up.
 ErrorDocument 404 /404.html
 ErrorDocument 422 /422.html
 ErrorDocument 500 /500.html
 ErrorDocument 502 /502.html
 ErrorDocument 503 /503.html

 LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b" common_forwarded
 ErrorLog /var/log/apache2/YOUR_SERVER_FQDN_error.log
 CustomLog /var/log/apache2/YOUR_SERVER_FQDN_forwarded.log common_forwarded
 CustomLog /var/log/apache2/YOUR_SERVER_FQDN_access.log combined env=!dontlog
 CustomLog /var/log/apache2/YOUR_SERVER_FQDN.log combined
</VirtualHost>

}}}

== Troubleshooting common issues ==

See [[gitlab/troubleshooting]]

== Tips and tweaks ==

See [[/tweaks|Tweaks for GitLab]]
Line 342: Line 240:
You can reach the maintainers of the gitlab package via

 1. Matrix at #debian-gitlab:poddery.com ([[https://chat.poddery.com/#/room/#debian-gitlab:poddery.com|join via browser]])
 1. IRC #debian-gitlab on OFTC network ([[https://webchat.oftc.net/?channels=debian-gitlab&uio=MT11bmRlZmluZWQb1|join via browser]])

== Maintainer's corner ==

 1. Installing gitlab on an lxc container to test - See [[gitlab/lxc]]
 1. Updating gitlab package to newer versions - See [[Teams/Ruby/Packaging/newUpstreamRailsApp]]
 1. Backport/Fasttrack checklist - See [[gitlab/BackportChecklist]]
 1. Dependencies Transitions checklist - See [[gitlab/DependenciesTransitions]]
 1. Managing Components - See [[gitlab/ManagingComponents]]
 1. Plan to move gitlab-common binary to gitlab-shell source package - See [[gitlab/gitlab-common-to-gitlab-shell-plan]]

'''TODO'''
 1. Aim to get gitlab back in main by bullseye release by packaging all node dependencies. [[Javascript/Nodejs/Tasks/gitlab|current status]] This is now an Outreachy project (from December 2019 to March 2020).
 1. Get autopkgtest working so we can detect problems when someone updates dependencies without coordinating with us. [[https://git.fosscommunity.in/debian-ruby/TaskTracker/-/issues/154|Current Status]]

== Omnibus Packages ==

Note: this section is about the installation of upstream-provided unofficial packages.

== Install ==
all actions are performed under the root user, in ~ unless otherwise noted.

=== Step 1 ===
navigate to https://about.gitlab.com/install/ and copy down the link to the Debian deb package.

as of this writing @ June 5, 2014

run

 *wget https://downloads-packages.s3.amazonaws.com/debian-7.4/gitlab_6.9.2-omnibus-1_amd64.deb

=== Step 2 ===
run
 *dpkg -i gitlab*

=== Step 3 ===
--(i got errors 1st time around 2nd time around gitlab looked like it set everything and ran well.)--

To avoid errors, execute ''/opt/gitlab/embedded/bin/runsvdir-start'' for one minute, more or less (tested in 7.9.0 and 7.9.1 omnibus versions).

run
 *gitlab-ctl reconfigure

to verify that things are running

run
 *gitlab-ctl status

=== Step 4 ===
navigate to your servers IP address or domain name, and login as:

user: root
password: 5iveL!fe

== External Resources ==
https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md
You can reach the maintainers of the gitlab package via

 1. Matrix at `#debian-gitlab:poddery.com` ([[https://chat.poddery.com/#/room/#debian-gitlab:poddery.com|join via browser]])
 1. IRC `#debian-gitlab` on OFTC network ([[https://webchat.oftc.net/?channels=debian-gitlab&uio=MT11bmRlZmluZWQb1|join via browser]])
 1. Via XMPP at `#debian-gitlab#poddery.com@matrix.org`

Documentation for [[gitlab/maintainers_corner|gitlab maintainers]]

Gitlab is a git front end with repository management, graphs, links, goodies, commands to run, and review capabilities similar in feel to a self-hosted ?GitHub.

A new feature release of gitlab flows in the following direction: devel -> staging -> experimental -> unstable -> fasttrack-staging -> fasttrack (experimental and unstable may be skipped during freeze and transitions).

See /omnibus if you are looking for instructions to install upstream provided packages.

New upstream releases (including security updates) are announced at https://about.gitlab.com/releases/categories/releases/ and available as RSS feed https://about.gitlab.com/security-releases.xml.

Debian is running its own Instance of GitLab under https://salsa.debian.org, which is not based on the packaged version.

Note 1: For a smooth upgrade experience, always stay on the latest major version of gitlab. For example, if latest version of gitlab is 12.0.0 and you are currently on 11.3.6, then update to 12.0.0 as soon as possible, certainly before the debian package is updated to 13.x. Ideally, you should update as soon as a new version with security updates is available.

Note 2: It is recommended to subscribe to changes in this wiki page or frequently check this page for updates. Alternatively, you can subscribe to https://tracker.debian.org/pkg/gitlab to get notified when new versions are uploaded.

Make sure contrib section is enabled for official repos.

Story of Gitlab packaging project/FAQ about Gitlab packaging

Gitlab Inc sponsored the packaging effort for 6+ years (2016-2022). Currently looking for donations at https://opencollective.com/debian-gitlab.

Though the dependencies are so many, the work benefits Debian immensely by maintaining many important build tools like webpack, rollup, babel, npm, yarn... And frameworks like ruby on rails.

The situation in packaging ?JavaScript modules is considerably improved over the years thanks to this packaging work. It took over 2 years for packaging handlebars_assets gem for diaspora because its embedded ?JavaScript library was using tools like gulp, webpack, jison etc and none of this was packaged for Debian. The whole ?JavaScript build tools were untouched for years in Debian and instead reverse engineering of the build tools for specific libraries was the norm (for example jquery), it was very hard and not scalable.

Out of 1600+ node modules gitlab needs, we have 1200+ modules already packaged. It is not impossible to have it in main (it was in main earlier before the nodejs modules exploded exponentially and if some more people join the team, currently it is mostly a single person work and at times some new people helping out with a handful of dependencies. I don't think it is much harder if you take whole gnome or KDE as comparison. We are able to pull it off because of team work. This project have also brought many new contributors to Debian.

While we might love long term supported releases, calling anything moving fast as insane and not able to adapt to change is a recipe for Debian becoming irrelevant over time. Many just want distros to be only a base os for shipping containers but that is not necessarily a good thing for users to have dependency on a single project for updates and lose choice and flexibility.

We created https://fasttrack.debian.net to serve gitlab as it did not fit into a debian stable release cycle and currently not just gitlab, but matrix synapse and virtual box is also shipped via FastTrack.

New changes

  1. From gitlab 14.7.7: gitlab user needs to write to /var/lib/gitlab/.gem so if you installed gems manually as root user, you will need to update permissions or remove this directory. Gitlab package now installs required unpackaged gems in that directory automatically.
  2. From gitlab 14.2.6: postgresql database should be updated to 13 before installing gitlab 14.2. See gitlab/postgresql-update for steps to upgrading postgresql to 13.

  3. From gitlab 14.0.10: We no longer require a work around to install grpc and google-protobuf gems from rubygems.org, packaged versions now work.
  4. From 2021 July 23: We no longer require the personal repo of gitlab maintainer to install gitlab, all golang packages can now be added to fasttrack.debian.net directly. Thanks to Akshay S Dinesh for fixing this long pending bug (See https://salsa.debian.org/fasttrack-team/support/-/issues/8 for details).

  5. New workaround from gitlab 13.12.3: You need to use google-protobuf from rubygems.org (see below for details).

  6. New from gitlab 13.10.4: Since this version includes gitlab-workhorse golang binary, it was moved to people.debian.org/~praveen/gitaly and should now include contrib section.
  7. New in gitlab 13.6.7-1: New user created after a fresh installation should be approved using gitlab-rails-console. See gitlab#your_account_is_awaiting_approval_from_your_GitLab_administrator for steps to approving users and creating a user with Administrative privileges.

  8. New in gitlab 13.3.8-1: You will need to install grpc gem from rubygems.org gem install -v 1.30.2 grpc (more details below). If you run gitaly on a different machine, you will need to do this on that machine as well.

  9. New in gitlab 13.2.6-3: We have switched to puma as application server replacing unicorn. Upstream already made the switch from 12.9 and unicorn support will be dropped in gitlab 14.0. They saw a memory reduction of 37% in gitlab.com after the switch. See more details about this switch at this upstream blog post https://about.gitlab.com/blog/2020/07/08/migrating-to-puma-on-gitlab/. puma defaults to listening only on unix sockets and if you are running gitaly on a different machine, then you will have to edit /etc/gitlab/puma.rb to bind to tcp:// url as well.

Bullseye FastTrack (Recommended)

gitlab 15.3.2 is available in Bullseye FastTrack (no open security issues).

Add fasttrack.debian.net as a trusted repo for apt,

# apt install fasttrack-archive-keyring ca-certificates

And add the following lines for fasttrack repo:

deb https://fasttrack.debian.net/debian/ bullseye-fasttrack main contrib
# For dependency packages not in testing only temporarily due to freeze, transitions or delayed by backports-new or NEW.
deb https://fasttrack.debian.net/debian/ bullseye-backports-staging main contrib

You will also need official bullseye-backports repo:

deb http://deb.debian.org/debian bullseye-backports main contrib

Note: You may also use a mirror of fasttrack repo like http://mirror.linux.pizza/debian-fasttrack/

and install gitlab

# apt update
# apt install gitlab-apt-pin-preferences
# apt install gitlab

Unstable (be careful when updating packages)

Gitlab 13.4.7 is available in unstable (many security release behind, see experimental for latest security updates).

We try to keep the version in unstable in a good shape with the latest security updates, but some times dependency updates break gitlab.

Now install gitlab

# apt install gitlab

Known Issues

Currently gitlab installation is broken due to a change in libsass. See 953415 for more details.

A work around is to downgrade libsass and libsass-dev to 3.6.1. Use http://snapshot.debian.org/package/libsass/3.6.1-1/ and hold it at the older version.

# wget http://snapshot.debian.org/archive/debian/20190705T210019Z/pool/main/libs/libsass/libsass-dev_3.6.1-1_amd64.deb

# wget http://snapshot.debian.org/archive/debian/20190705T210019Z/pool/main/libs/libsass/libsass1_3.6.1-1_amd64.deb

# dpkg -i libsass1_3.6.1-1_amd64.deb libsass-dev_3.6.1-1_amd64.deb

# apt-mark hold libsass1 libsass-dev

See gitlab#gitlab_crash_work_around_.28install_grpc_from_rubygems.org.29 for installing grpc gem from rubygems.org (just use apt install ruby2.7 for installing ruby)

Downgrade ruby-autoprefixer-rails and node-autoprefixer packages to 10.3.1.0+dfsg1+~cs14.6.19-2 using https://snapshot.debian.org/package/node-autoprefixer/10.3.1.0%2Bdfsg1%2B%7Ecs14.6.19-2/ and hold them to this version.

# apt-mark hold node-autoprefixer ruby-autoprefixer-rails

See 1009245

Downgrade ruby-github-linguist till gitaly is adapted to find languages.json from gem-install layout.

Get older version from https://snapshot.debian.org/package/ruby-github-linguist/7.12.2-1/

# apt-mark hold ruby-github-linguist

Experimental - During freeze and transitions

gitlab 15.2.2 is available in experimental (see below for security fixes).

If you are using experimental for the first time, check DebianExperimental.

You will have to follow the notes mentioned in unstable section above.

Experimental/unstable Staging

When gitlab is not ready for official experimental/unstable (for example some dependencies need to clear NEW queue), it will be available from this repo.

gitlab 15.3.1 is available in gitlab/staging

You will have to follow the notes mentioned in unstable section above.

This section moved to gitlab/staging.

Gitlab on older releases

These versions no longer receive any secuity updates and it is recommended to upgrade to Debian 11 Bullseye to continue recieving security updates.

Gitlab with apache2

Gitlab can use apache instead of nginx. The (gitlab-recipes repository) instructions are wrong - apache supports proxying to UNIX sockets so there's no need to change any gitlab configuration to use TCP.

Basically you will have to:

  • disable nginx
  • enable apache modules:
    • mod_rewrite
    • mod_ssl (if needed)
    • mod_proxy
    • mod_proxy_http
    • mod_headers
  • add/modify apache configuration file

a2enmod rewrite ssl proxy_http headers

See below for Apache configuration file example (using Let's Encrypt SSL certificates and HTTP to HTTPS redirect). Replace YOUR_SERVER_FQDN string with your domain (e.g. git.example.org).

<VirtualHost *:80>
        ServerName YOUR_SERVER_FQDN
        Redirect / https://YOUR_SERVER_FQDN/
</VirtualHost>

<VirtualHost *:443>
        SSLCertificateFile    /etc/letsencrypt/live/YOUR_SERVER_FQDN/fullchain.pem
        SSLCertificateKeyFile /etc/letsencrypt/live/YOUR_SERVER_FQDN/privkey.pem
        Include /etc/letsencrypt/options-ssl-apache.conf
        Header add Strict-Transport-Security: "max-age=15768000;includeSubdomains"
        ProxyPreserveHost On

        ServerName YOUR_SERVER_FQDN

        # Ensure that encoded slashes are not decoded but left in their encoded state.
        # http://doc.gitlab.com/ce/api/projects.html#get-single-project
        AllowEncodedSlashes NoDecode

        <Location />
                Require all granted
                ProxyPassReverse https://YOUR_SERVER_FQDN/
        </Location>

        RewriteEngine on
        #Forward all requests to gitlab-workhorse except existing files like error documents
        RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR]
        RewriteCond %{REQUEST_URI} ^/uploads/.*
        RewriteRule .* unix:/run/gitlab/gitlab-workhorse.socket|http://YOUR_SERVER_FQDN%{REQUEST_URI} [P,QSA,NE]

        RequestHeader set X_FORWARDED_PROTO 'https'
        RequestHeader set X-Forwarded-Ssl on

        # needed for downloading attachments
        DocumentRoot /var/lib/gitlab/public

        # Set up apache error documents, if back end goes down (i.e. 503 error) then a maintenance/deploy page is thrown up.
        ErrorDocument 404 /404.html
        ErrorDocument 422 /422.html
        ErrorDocument 500 /500.html
        ErrorDocument 502 /502.html
        ErrorDocument 503 /503.html

        LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b" common_forwarded
        ErrorLog /var/log/apache2/YOUR_SERVER_FQDN_error.log
        CustomLog /var/log/apache2/YOUR_SERVER_FQDN_forwarded.log common_forwarded
        CustomLog /var/log/apache2/YOUR_SERVER_FQDN_access.log combined env=!dontlog
        CustomLog /var/log/apache2/YOUR_SERVER_FQDN.log combined
</VirtualHost>

Troubleshooting common issues

See gitlab/troubleshooting

Tips and tweaks

See Tweaks for GitLab

Contact maintainers

You can reach the maintainers of the gitlab package via

  1. Matrix at #debian-gitlab:poddery.com (join via browser)

  2. IRC #debian-gitlab on OFTC network (join via browser)

  3. Via XMPP at #debian-gitlab#poddery.com@matrix.org

Documentation for gitlab maintainers