Advanced dependency instructions

The following are dependency installation instructions for systems other than those covered in the main dependency installation instructions.

These instructions may contain advanced configuration options that may not be officially supported.

macOS

GDK supports macOS 10.14 (Mojave) and later. To install dependencies for macOS:

Install Homebrew to get access to the brew command for package management.
Clone the gitlab-development-kit project so you have access to the project's Brewfile. You can:
- Reuse an existing checkout if you have one, but make sure it's up to date.
- Use this check out again when you install GDK.
Install nvm. It should automatically configure it for your shell.
Install the GDK required version of node using nvm, such as:
```
nvm install 16.14.0
```
In the gitlab-development-kit checkout, run the following brew commands:
```
brew bundle
brew install go postgresql@12 minio/stable/minio rbenv redis yarn
```
1. Add $(brew --prefix)/opt/postgresql@12/bin to your shell's PATH environment variable. For example, for macOS default zsh shell:
```
export PATH="$(brew --prefix)/opt/postgresql@12/bin:$PATH"
```
Configure rbenv for your shell.
Install the GDK required version of Ruby using rbenv, such as:
```
rbenv install 2.7.5
```

Workaround thin installation issues on macOS by running:

bundle config --local build.thin --with-cflags='"-Wno-error=implicit-function-declaration"'

To ensure the re2 gem is built correctly, explicitly set the directory where brew installed re2:
```
bundle config --local build.re2 --with-re2-dir=$(brew --prefix re2)
```

Ubuntu and Debian

The following are instructions for Ubuntu and Debian users that don't want GDK to manage their dependencies.

These instructions help you install dependencies for Ubuntu, assuming you're using an active LTS release (16.04, 18.04, 20.04) or higher, and Debian:

Install git and make.
Install Yarn.
Run make bootstrap-packages. This is a light subset of make bootstrap that runs apt-get update and then apt-get install on the packages found in packages_debian.txt.
```
make bootstrap-packages
```

Install PostgreSQL and MinIO. Run the following commands:

sudo apt update && sudo apt install postgresql postgresql-contrib
sudo curl "https://dl.min.io/server/minio/release/linux-amd64/minio" --output /usr/local/bin/minio
sudo chmod +x /usr/local/bin/minio

Check the required Go version in .tool-versions. You may be able to install the required version using apt. Check the available versions for:
- Ubuntu.
- Debian.
Install Go using one of the following methods:
- If available for your version of Ubuntu or Debian, run sudo apt install golang.
- If the required version is only available as a backport in Ubuntu, or Debian, use the backport package. You may have to update your $PATH so the backported version of Go is used.
- If unavailable, install it manually. See the official Go installation instructions.
Check that make bootstrap-packages installed redis-server version 5.0 or newer (apt list redis-server). Install Redis 5.0 or newer manually, if you don't already have it.
Install Ruby using rbenv. Install rbenv:
```
sudo apt install rbenv
```
Run rbenv init to get instructions for what to add to your shell configuration file. For more information, see the rbenv docs. Note:
- If the required Ruby version in .tool-versions isn't installable, you must get the ruby-build plugin and build it.
- You must select the Ruby version instead of your distributions default one (if any). See the the rbenv instructions. For example, echo 2.7.5 >~/.rbenv/version.
Install GDK.

Install dependencies for other Linux distributions

The process for installing dependencies on Linux depends on your Linux distribution.

Unless already set, you might have to increase the watches limit of inotify for frontend development tools such as webpack to effectively track file changes. See Inotify Watches Limit for details and instructions about how to apply this change.

Arch and Manjaro Linux

The following are instructions for Arch and Manjaro users that don't want GDK to manage their dependencies with asdf. These steps should also work for other Arch-based distribution that use systemd.

To install dependencies for Arch Linux:

Install git and make

In the root of the gitlab-development-kit directory, run:

sudo pacman -S $(sed -e 's/#.*//' packages_arch.txt)

Install runit-systemd.

Install runit on Arch and Manjaro Linux

The Arch Linux core repository no longer contains the runit package. You must install runit-systemd from the Arch User Repository (AUR).

If you're installing dependencies with asdf, runit-systemd is installed as part of the make bootstrap command.

You can use an AUR package helper:

For pacaur (https://github.com/E5ten/pacaur):
```
pacaur -S runit-systemd
```
For pikaur (https://github.com/actionless/pikaur):
```
pikaur -S runit-systemd
```
For yay:
```
yay -S runit-systemd
```

Fedora

NOTE: These instructions don't account for using asdf for managing some dependencies.

We assume you are using Fedora >= 31.

NOTE: Fedora 32 ships PostgreSQL 11.x and Fedora 32+ ships PostgreSQL 12.x in default repositories. You can use postgresql:11 or postgresql:12 module to install PostgreSQL 11 or 12. But keep in mind that replaces the default version of PostgreSQL package, so you cannot use both versions at once.

sudo dnf module enable postgresql:12 # or postgresql:11

To install dependencies for Fedora:

sudo dnf install postgresql postgresql-libs redis libicu-devel \
  git git-lfs ed make cmake rpm-build gcc-c++ krb5-devel go postgresql-server \
  postgresql-contrib postgresql-devel re2 GraphicsMagick re2-devel sqlite-devel \
  perl-Digest-SHA perl-Image-ExifTool rsync
sudo curl "https://dl.min.io/server/minio/release/linux-amd64/minio" --output /usr/local/bin/minio
sudo chmod +x /usr/local/bin/minio

You may have to install Redis 5.0 or newer manually.

runit

You also have to install runit manually.

Although the following instructions work for runit version 2.1.2, be sure to read the up-to-date installation instructions on the website before continuing.

Download and extract the runit source code to a local folder to compile it:

wget http://smarden.org/runit/runit-2.1.2.tar.gz
tar xzf runit-2.1.2.tar.gz
cd admin/runit-2.1.2
sed -i -E 's/ -static$//g' src/Makefile
./package/compile
./package/check

Ensure all binaries in command/ are accessible from your PATH (for example, symlink / copy them to /usr/local/bin)

CentOS

NOTE: These instructions don't account for using asdf for managing some dependencies.

We assume you are using CentOS >= 8.

To install dependencies for CentOS (tested on CentOS 8.2):

sudo dnf module enable postgresql:12
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install postgresql-server postgresql-devel libicu-devel git git-lfs cmake \
  gcc-c++ go redis ed fontconfig freetype libfreetype.so.6 libfontconfig.so.1 \
  libstdc++.so.6 npm re2 re2-devel GraphicsMagick perl-Image-ExifTool \
  rsync sqlite-devel make
sudo curl "https://dl.min.io/server/minio/release/linux-amd64/minio" --output /usr/local/bin/minio
sudo chmod +x /usr/local/bin/minio

# This example uses Ruby 2.7.5. Substitute with the current version if different.
sudo rvm install 2.7.5
sudo rvm use 2.7.5
#Ensure your user is in rvm group
sudo usermod -a -G rvm <username>
#add iptables exceptions, or sudo service stop iptables

Follow runit install instruction to install it manually.

Red Hat Enterprise Linux

NOTE: These instructions don't account for using asdf for managing some dependencies, and were tested on RHEL 8.3.

To install dependencies for RHEL:

sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf module install postgresql:12 redis:5 nodejs:14 go-toolset
sudo dnf install postgresql-server postgresql-devel libicu-devel git git-lfs cmake \
  gcc-c++ go redis ed fontconfig freetype libfreetype.so.6 libfontconfig.so.1 \
  libstdc++.so.6 npm re2 re2-devel GraphicsMagick perl-Image-ExifTool \
  rsync sqlite-devel make
sudo curl "https://dl.min.io/server/minio/release/linux-amd64/minio" --output /usr/local/bin/minio
sudo chmod +x /usr/local/bin/minio

# This example uses Ruby 2.7.5. Substitute with the current version if different.
sudo rvm install 2.7.5
sudo rvm use 2.7.5
#Ensure your user is in rvm group
sudo usermod -a -G rvm <username>
#add iptables exceptions, or sudo service stop iptables

Follow runit install instruction to install it manually.

NOTE: Although RHEL8 has a FIPS-compliant mode and GitLab can be installed with it enabled, GitLab is not FIPS-compliant and doesn't run correctly with it enabled. Epic &5104 tracks the status of GitLab FIPS compliance.

OpenSUSE

NOTE: These instructions don't account for using asdf for managing some dependencies.

This was tested on openSUSE Tumbleweed (20200628).

NOTE: OpenSUSE LEAP is currently not supported, because since a8e2f74d PostgreSQL 11+ is required, but LEAP 15.1 includes PostgreSQL 10 only.

To install dependencies for OpenSUSE:

sudo zypper dup
# now reboot with "sudo init 6" if zypper reports:
# There are running programs which still use files and libraries deleted or updated by recent upgrades.
sudo zypper install libxslt-devel postgresql postgresql-devel redis libicu-devel git git-lfs ed cmake \
        rpm-build gcc-c++ krb5-devel postgresql-server postgresql-contrib \
        libxml2-devel libxml2-devel-32bit findutils-locate GraphicsMagick \
        exiftool rsync sqlite3-devel postgresql-server-devel \
        libgpg-error-devel libqgpgme-devel yarn curl wget re2-devel
sudo curl "https://dl.min.io/server/minio/release/linux-amd64/minio" --output /usr/local/bin/minio
sudo chmod +x /usr/local/bin/minio

Install go manually using Go official installation instructions, for example:

curl -O "https://dl.google.com/go/go1.14.4.linux-amd64.tar.gz"
sudo tar xpzf go1.14.4.linux-amd64.tar.gz -C /usr/local

Ensure that node has write permissions to install packages using:

mkdir -p ~/mynode/bin ~/mynode/lib
npm config set prefix ~/mynode

Install runit (it is no longer included in OpenSUSE):

wget http://smarden.org/runit/runit-2.1.2.tar.gz
tar xzf runit-2.1.2.tar.gz
cd admin/runit-2.1.2
sed -i -E 's/ -static$//g' src/Makefile
./package/compile
./package/check
sudo ./package/install

Set up local Ruby 2.7 environment, for example using RVM:

curl -sSL -o setup_rvm.sh "https://get.rvm.io"
chmod a+rx setup_rvm.sh
./setup_rvm.sh
source  /home/ansible/.rvm/scripts/rvm
rvm install 2.7.5

Append these lines to your ~/.bashrc:

# to find binaries installed by yarn command
export PATH="$HOME/.yarn/bin:$PATH"
# to find sshd and redis-server in default path
export PATH="$PATH:/usr/sbin"
# to find go
export PATH="$HOME/go/bin:/usr/local/go/bin:$PATH"
# local node packages
export PATH="$HOME/mynode/bin:$PATH"
# GDK is confused with OSTYPE=linux (suse default)
export OSTYPE=linux-gnu

And reload it using:

source ~/.bashrc

Now determine that the current Ruby version is 2.7.x:

ruby --version
ruby 2.7.5p203 (2021-11-24 revision f69aeb8314) [x86_64-linux]

If it's different (for example Ruby 2.7 - system default in Tumbleweed), you must sign in again.

The following bundle config option is recommended before you run gdk install to avoid problems with the embedded library inside gpgme:

bundle config build.gpgme --use-system-libraries

Now you can proceed to set up GDK.

Void Linux

To run GDK on Void, you must install ruby with development headers, gem binary dependencies, go, postgresql with client, development headers and shared libraries, sqlite, redis:

sudo xbps-install -Su
sudo xbps-install ruby ruby-devel minio re2 re2-devel icu icu-libs icu-devel \
  go redis yarn GraphicsMagick sqlite sqlite-devel  pkg-config \
  postgresql13 postgresql13-client postgresql13-contrib postgresql-libs postgresql-libs-devel

Install FreeBSD dependencies

To install dependencies for FreeBSD:

sudo pkg install postgresql10-server postgresql10-contrib \
redis go node icu krb5 gmake re2 GraphicsMagick p5-Image-ExifTool git-lfs minio sqlite3

Windows 10/Windows 11

You can set up GDK on Windows by using the Windows Subsystem for Linux (version 2 only).

Setting up the Windows Subsystem for Linux:

Open PowerShell as Administrator and run:

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
wsl --set-default-version 2

Restart your computer when prompted.

Install your Linux distribution of choice using the Windows Store. The available distribution options include:

Ubuntu
OpenSUSE
SLES
Kali Linux
Debian GNU/Linux

We have validated that Ubuntu 20.04 works correctly, but other distributions may also work.

Launch the distribution of choice.

You must ensure that your Linux distribution uses WSL version 2. Open PowerShell with administrator privileges, and then run the following:

# If the command below does not return a list of your installed distributions,
# you have WS1.
wsl -l

You can upgrade your WSL.

If you noticed your distribution of choice is an older subsystem, you can upgrade it by running:

# Get the name of your subsystem
wsl -l
# Run the following command
wsl --set-version <your subsystem name here>

Known issues with Windows Subsystem for Linux

Directories

Using a directory path with a space in it causes the install to fail (for example, using the default home directory of the Windows user, where you've possibly used your full name). This is an open issue.

Additionally, using a directory path in Windows file system mount points (such as /mnt/c or /mnt/d) results in permissions issues. Instead, you must use a path inside the WSL OS, such as inside /home/<user>/. If you must access the files from Windows, you can go to \\wsl$ in Explorer to browse the file system. For example, /home/sid/dev/gitlab-development-kit would be visible at \\wsl$\Ubuntu-20.04\home\sid\dev\gitlab-development-kit.

Performance

WSL allocates up to 50% of your RAM by default for the Linux OS.

Apply custom patches for Ruby

Some functions (and specs) require a special Ruby installed with additional patches. These patches are already applied when running on GitLab CI/CD or when using GitLab Compose Kit, but since GitLab Development Kit uses asdf they must be manually enabled.

To recompile Ruby with adding additional patches do the following:

asdf uninstall ruby

# Compile Ruby 2.7.5
export RUBY_APPLY_PATCHES="$(cat <<EOF
https://gitlab.com/gitlab-org/gitlab-build-images/-/raw/master/patches/ruby/2.7.5/debug-segfault.patch
https://gitlab.com/gitlab-org/gitlab-build-images/-/raw/master/patches/ruby/2.7.5/thread-memory-allocations-2.7.patch
EOF
)"
asdf install ruby 2.7.5

# Compile Ruby 3.0.4
export RUBY_APPLY_PATCHES="$(cat <<EOF
https://gitlab.com/gitlab-org/gitlab-build-images/-/raw/master/patches/ruby/3.0.4/thread-memory-allocations-3.0.patch
EOF
)"
asdf install ruby 3.0.4

You can later verify that patches were properly applied:

$ ruby -e 'puts Thread.trace_memory_allocations'
false

Next Steps

After you've completed the steps on this page, install GDK.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Advanced dependency instructions

macOS

Ubuntu and Debian

Install dependencies for other Linux distributions

Arch and Manjaro Linux

Install runit on Arch and Manjaro Linux

Fedora

runit

CentOS

Red Hat Enterprise Linux

OpenSUSE

Void Linux

Install FreeBSD dependencies

Windows 10/Windows 11

Known issues with Windows Subsystem for Linux

Directories

Performance

Apply custom patches for Ruby

Next Steps

FilesExpand file tree

advanced.md

Latest commit

History

advanced.md

File metadata and controls

Advanced dependency instructions

macOS

Ubuntu and Debian

Install dependencies for other Linux distributions

Arch and Manjaro Linux

Install runit on Arch and Manjaro Linux

Fedora

runit

CentOS

Red Hat Enterprise Linux

OpenSUSE

Void Linux

Install FreeBSD dependencies

Windows 10/Windows 11

Known issues with Windows Subsystem for Linux

Directories

Performance

Apply custom patches for Ruby

Next Steps