前期准备
- MacOS
- Linux
克隆 git-development-kit 代码库
Bootstrap
- MacOS
- Linux
安装配置 gdk
- MacOS
- Linux
启动 gitlab
创建 main-jh 分支
设置本地网络
登录 root 用户
申请 gitlab license 激活 gitlab 服务
运行本地测试
Debug GitLab Rails Server
使用 Table+ 查看数据库
运行功能测试
常见问题收集
最后

安装开发环境帮助文档

文档假设安装环境为 MacOS 或者 Linux（在两个系统有差别时会分标题列出），在安装过程中，请同时参考 gitlab-development-kit 官方文档。

gitlab-development-kit doc

前期准备

MacOS

请确保以下工具正确安装

homebrew
最新的 Xcode 和 Xcode Command Line Tools
确保你的机器可以正常访问必需的海外技术资源
git，建议升级 brew upgrade git
make
asdf, brew install asdf，请使用 asdf 来管理依赖，在开发过程中会使用 gdk update 进行升级，不用 asdf 会非常麻烦

Linux

请安装好下列前置依赖：

asdf
ExifTool
runit（不推荐使用包管理器安装，小心弄坏 systemd）
运行下列命令（注意检查要被卸载的包，避免意外卸载掉重要的包）：

sudo apt install build-essential git graphicsmagick-imagemagick-compat libreadline-dev sqlite3 \
libsqlite3-dev libre2-dev build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev \
  libncurses5-dev libffi-dev curl openssh-server libxml2-dev libxslt-dev \
  libcurl4-openssl-dev libicu-dev logrotate rsync python-docutils pkg-config cmake \
  libkrb5-dev libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev git-core \
  postfix libgpgme11-dev ruby-gpgme

其中，Postfix 可选 Local 配置。

如果在接下来的步骤中遇到了依赖问题，可以参阅Gitlab 在 Linux 上的依赖和搜索错误信息（放轻松啦，Linux 就是这样子的啦，哪有一帆风顺的，饮茶压压惊先）。

克隆 git-development-kit 代码库

这个代码库包含着 setup gitlab 环境的代码，不包含 gitlab 的相关代码。

使用下面命令 clone repo 到 gdk 文件夹 (没有使用 gitlab-development-kit 的名字，而是起了别名)。我喜欢用 ssh 的 url，也可以换成 https

git clone git@gitlab.com:gitlab-org/gitlab-development-kit.git gdk

请注意：

不要把 gdk repo 放到嵌套太深的文件夹中，因为后期会用到一些 socket 文件，而 socket 文件有 100 字符的限制，嵌套太深的文件夹很容易超出限制导致报错，推荐放到类似 /Users/xxx/work/gdk
clone repo 之后不要轻易地修改 gdk 的文件夹名字，不少配置都是根据 clone repo 的名字生成的，修改之后很容易出错。

Bootstrap

MacOS

进入 gdk 文件夹，运行下面命令进行安装：

gdk_debug=true make bootstrap # 会安装 ruby,go,node 等等

环境变量 gdk_debug 可以查看安装过程中的 debug log。安装过程中可以关注一下 log，可能包含需要添加到.bash_profile 或者 .zshrc 里面环境变量。

Linux

进入 gdk 文件夹，运行下面命令：

gdk_debug=true make bootstrap

如果你使用的不是国外常见的发行版（Ubuntu, Debian, Arch, Fedora），比如说 Deepin，bootstrap 会失败，说不认识 Deepin，此时需要在gdk/support/bootstrap-common.sh:28附近的SUPPORTED_LINUX_PLATFORMS中新增行：['deepin']='Deepin' \.

安装配置 gdk

MacOS

如果是 M1 芯片的 mac，需要配置一下环境变量到.bash_profile 或者 .zshrc

export PKG_CONFIG_PATH="$(brew --prefix)/opt/libffi/lib/pkgconfig:$PKG_CONFIG_PATH"
export PKG_CONFIG_PATH="$(brew --prefix)/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"
export LDFLAGS="$LDFLAGS:-L$(brew --prefix)/opt/libffi/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libffi/include"
export CPATH=$(brew --prefix)/include
export LIBRARY_PATH=$(brew --prefix)/lib
export LD_LIBRARY_PATH=$(brew --prefix)/lib
export GIT_APPEND_BUILD_OPTIONS=LIBPCREDIR=$(brew --prefix)/opt/pcre2

首先需要安装 gitlab-development-kit gem，这个 gem 包含了 gdk 可执行命令。

gem install gitlab-development-kit

接下来就是 clone gitlab repo, 时间较长耐心等待, 同时配置运行 gitlab 的其他组件。

gdk install gitlab_repo=git@gitlab.com:gitlab-jh/jh-team/gitlab.git gdk_debug=true

repo git@gitlab.com:gitlab-jh/jh-team/gitlab.git 是极狐团队专用给 upstream 提交 MR 的，具体请参考这个 ppt

在 gdk install 的过程中，如果碰到错误，首先请不要慌！不要慌！不要慌！：）

仔细查看错误的 log，在这里看下有没有解决方案：常见问题收集。

如果运气不好没找到，那么就试试 gdk update，有时候可能就自动 fix 了

gdk update gdk_debug=true

如果还是不行，考虑发消息求助其他极狐的小伙伴，或者找你的 buddy 帮你：）

Linux

确认你的系统的 inotify 足够大，因为 webpack 和 IDE 都会使用它：

sysctl fs.inotify

如果 inotify 低于 10 万的话，运行下列命令并重启系统：

echo fs.inotify.max_user_watches=100000 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

在 gdk 目录下运行命令：

gdk install gitlab_repo=git@gitlab.com:gitlab-jh/jh-team/gitlab.git gdk_debug=true

遇到问题时请仔细查看错误的 log，在这里看下有没有解决方案：常见问题收集。

启动 gitlab

可以使用 gdk 的命令来启动 gitlab 和其他组件

gdk start #启动所有组件，
gdk tail #查看所有组件的 log
gdk stop #停止所有组件
gdk status #查看组件运行状态
#更多命令请运行 gdk 查看帮助

在正确启动的环境之后，命令 gdk status 应该输出所有组件都是run状态的 log，如果有down的组件，请运行 gdk tail xxx 具体查看 log

run: /Users/.../services/gitlab-workhorse: (pid 88242) 417s, normally down; run: log: (pid 87924) 418s

run: /Users/.../services/postgresql: (pid 87928) 418s, normally down; run: log: (pid 87919) 418s

run: /Users/.../services/praefect: (pid 88235) 417s, normally down; run: log: (pid 87921) 418s

run: /Users/.../services/praefect-gitaly-0: (pid 88236) 417s, normally down; run: log: (pid 87923) 418s

run: /Users/.../services/rails-background-jobs: (pid 88243) 417s, normally down; run: log: (pid 87925) 418s

run: /Users/.../services/rails-web: (pid 88245) 417s, normally down; run: log: (pid 87920) 418s

run: /Users/.../services/redis: (pid 88087) 418s, normally down; run: log: (pid 87922) 418s

run: /Users/.../services/sshd: (pid 88246) 417s, normally down; run: log: (pid 87918) 418s

run: /Users/.../services/webpack: (pid 88244) 417s, normally down; run: log: (pid 87926) 418s

创建 main-jh 分支

在后期的开发过程中，我们经常需要同时修改 GitLab repo 和 JiHu GitLab repo 的代码，所以我推荐大家在 GitLab repo 中添加极狐 GitLab 源，这样可以更方便的向 GitLab 和极狐 GitLab 提交代码。

有两个主要的分支：

一个是 master，是专门往 upstream gitlab 提交代码用的分支，指向 GitLab 源

一个是 main-jh，是专门给极狐程序员用的分支，指向极狐 GitLab 源

类似下面的效果

我们执行完 gdk install 之后，就有了 master 分支（指向 upstream gitlab），然后再使用下面的命令创建 main-jh 分支

git remote add jh git@jihulab.com:gitlab-cn/gitlab.git # 添加 jh 源
git fetch jh # pull 所有 jh 源的分支
git switch -c main-jh jh/main-jh # 创建 main-jh 分支，并指向 jh 源

#验证一下
git remote -v
# jh	git@jihulab.com:gitlab-cn/gitlab.git (fetch)
# jh	git@jihulab.com:gitlab-cn/gitlab.git (push)
# origin	git@gitlab.com:gitlab-jh/jh-team/gitlab.git (fetch)
# origin	git@gitlab.com:gitlab-jh/jh-team/gitlab.git (push)

git checkout master && git status -sb
# master...origin/master 说明 master 指向 origin 源，也就是 gitlab.com

git checkout main-jh && git status -sb
# main-jh...jh/main-jh 说明 main-jh 指向 jh 源，也就是 jihulab.com

#下载依赖
bundle install
yarn install

在 main-jh 分支中，因为有极狐自己的代码 (存放在 jh 目录中)，需要注意：

因为 gitlab/jh 文件夹下有极狐自己用的 Gemfile，所以在启动 rails server 的时候，如果发现有类似“找不到 tencentcloud-sdk-common gem” 的错误，需要在 gitlab/.bundle/config 里面添加BUNDLE_GEMFILE: "jh/Gemfile"，保证 jh/Gemfile 能正确加载
在执行 gdk update 的时候，当在 gitlab 目录下切换至 master 分支时，确保该目录中没有 jh 子目录。原因是在 gdk update 的时候需要确保没有任何极狐的代码被执行，也需要注释掉在 gitlab/.bundle/config 里面BUNDLE_GEMFILE: "jh/Gemfile", 确保 gdk update 顺利完成。可以添加下面的 bash_function 到你的 shell 中，通过 jh_gemfile 和 gl_gemfile 添加/删除 gitlab/.bundle/config 里面 BUNDLE_GEMFILE的内容，这两个方法在 gitlab repo 和 gitlab 上层的 gdk repo 都可以调用。每次新打开都可用的话，则复制下面的代码到 ~/.bash_profile 或者 ~/.zshrc

function jh_gemfile () {
  pwd=$(pwd)
  current_dir=`basename $pwd`
  if [ $current_dir != 'gdk' ] && [ $current_dir != 'gitlab' ]
  then
    echo 'run this in gitlab or gdk folder'
    return -1
  fi
  if [[ -d gitlab ]]
  then
    bundle_file="./gitlab/.bundle/config"
  else
    bundle_file="./.bundle/config"
  fi
  echo '---\nBUNDLE_SET: "without production"\nBUNDLE_JOBS: "5"\nBUNDLE_GEMFILE: "jh/Gemfile"' > $bundle_file
  echo "ADD jh/Gemfile in bundle/config"
}

function gl_gemfile () {
  pwd=$(pwd)
  current_dir=`basename $pwd`
  if [ $current_dir != 'gdk' ] && [ $current_dir != 'gitlab' ]
  then
    echo 'run this in gitlab or gdk folder'
    return -1
  fi
  if [[ -d gitlab ]]
  then
    bundle_file="./gitlab/.bundle/config"
  else
    bundle_file="./.bundle/config"
  fi
  echo '---\nBUNDLE_SET: "without production"\nBUNDLE_JOBS: "5"\n' > $bundle_file
  echo "REMOVE jh/Gemfile in bundle/config"
}

设置本地网络

当前是使用 http://localhost:3000 启动访问服务，设置本地网络后则可以使用 http://gdk.test:3000 请参照一下这个文档设置本地网络参数

设置之前请运行 gdk stop 暂停所有组件，如果设置完成后发现有访问不到 rails 服务或者 webpack 服务的情况，你需要把你的开发域名设置成不走代理，然后重新尝试

登录 root 用户

设置完成后，访问 gdk.test:3000，登录 root/5iveL!fe

搭建成功！激动！撒花！

申请 gitlab license 激活 gitlab 服务

向极狐的同事申请 license，拿到 license 后，登录 root，点击 Menu → Admin → Settings → General → License file，上传即可

运行本地测试

光登录成功还不够，还要能正确运行测试。推荐使用 rubymine 运行测试，介绍一下如何配置 rubymine rspec 的：

使用 rubymine 打开 gitlab repo，注意不是 gdk repo
选择 Edit Configuration，

点击左下角的Edit configurations templates
选择 rspec，在 Environment Variables 中添加 BUNDLE_GEMFILE=jh/Gemfile
然后打开一个测试文件，比如 terms_helper_spec.rb，运行测试，验证结果
其实在 gitlab repo 下运行 bundle exec rspec xxx_spec.rb 也可以。例如 bundle exec rspec spec/models/users_statistics_spec.rb

Debug GitLab Rails Server

有时候我们需要 debug gitlab rails 来帮助我们更好地理解原有逻辑，具体如下：

暂停 gdk 管理的 rails 服务，gdk stop rails-web
打开 rubymine，选择 Edit Configuration（类似“运行本地测试”章节）
新增一个 ruby 启动项，添加以下内容
1. ruby scripts: [gitlab-repo-path]/bin/rails
2. script arguments: s
3. working directory: [gitlab-repo-path]
4. Environment Variable:
```
 ENABLE_BOOTSNAP=true;RAILS_ENV=development;ACTION_CABLE_IN_APP=true;ACTION_CABLE_WORKER_POOL_SIZE=4;CUSTOMER_PORTAL_URL=http://gdk.test:5000
```

选择刚才添加的启动项，点击 debug 即可，

有另一个简单的方法，就是使用 gdk thin，它会停止使用 puma 来启动 rails，然后起一个 thin 的 server，这样就可以使用 binding.pry 来打断点调试了

使用 Table+ 查看数据库

不会连接数据库的程序员不是好程序员：）

下载 table+, https://tableplus.com/, 试用版免费，正式版需要申请 license
添加新的连接，选择 postgres
在 Host/Socket 中填入 gdk/postgresql 的文件夹地址，比如 /Users/chaomao/workspace/gdk/postgresql. 或者查看gitlab/config/database.yml本地数据库的具体连接情况.
port 填入 5432 , database 填入 gitlabhq_development
点击 Test 测试连接，connect 保存连接配置

运行功能测试

保证 chromedriver 不会被苹果系统安全相关设置阻挡，在 terminal 里面运行 chromedriver 命令，确保能正确启动
在 terminal 里面删除 proxy 相关的环境变量，取消科学上网的全局代理模式
运行测试需要依赖 webpack，请运行 gdk start，同时 webpack 默认会延迟编译 js 文件，所以第一次运行测试会 fail，第二次运行就 pass 了
推荐运行这个测试验证 bundle exec rspec ee/spec/features/epic_boards/epic_boards_spec.rb

常见问题收集

这是 Upstream 整理的安装问题，先去找下你遇到的问题在不在此: Troubleshooting GDK

缺少依赖。这是最常见的错误，一定要仔细看日志。有些日志比较隐蔽，比如：

 ERROR: 'support/exec-cd gitlab bundle exec rake dev:setup' failed. Retrying in 2 secs..

手动执行它，才看到了缺少 view_component 和 pg 的依赖：

 $ support/exec-cd gitlab bundle exec rake dev:setup
 Could not find view_component-2.61.0, pg-1.4.1 in any of the sources
 Run `bundle install` to install missing gems.

安装 asdf 前不应该配置这些环境变量，否则可能会出现问题：

 clang: clang: error: linker command failed with exit code 1 (use -v to see invocation)
 error: linker command failed with exit code 1 (use -v to see invocation)

报错 local error: tls: bad record MAC。
如果你用 ClashX Pro，记得打开增强模式（其他代理工具类似），否则可能出现某些请求不走代理的情况，会报此错误。

报错 LoadError：re2/lib/libre2.9.dylib。

 LoadError: dlopen(/Users/xxx/.asdf/installs/ruby/2.7.7/lib/ruby/gems/2.7.0/gems/re2-1.6.0/lib/re2.bundle, 0x0009): Library not loaded:'/opt/homebrew/opt/re2/lib/libre2.9.dylib'
 Reason: tried : '/opt/homebrew/opt/re2/lib/libre2.9.dylib' (no such file), '/usr/local/lib/libre2.9.dylib' (no such file), 'opt/homebrew/Cellar/re2/20221201/lib/libre2.9.dylib' (no such file) 

如果你用的 re2-20221201，所使用的是 libre2.10.dylib。你有两种解决方案：
1. 将re2降级到20220601版本
2. 将 opt/homebrew/Cellar/re2/20221201/lib/libre2.10.dylib 改为 opt/homebrew/Cellar/re2/20221201/lib/libre2.9.dyli

Webpack 异常退出。
很难受，错误日志（如下）只能看到 Killed，并不能看出退出的原因。后来才发现是机器内存不足导致的，从 4G 扩容到 8G，问题便被解决了。

 2023-01-05_19:54:58.65897 webpack               : graphql-tag enforces all fragment names across your application to be unique; read more about
 2023-01-05_19:54:58.65897 webpack               : this in the docs: http://dev.apollodata.com/core/fragments.html#unique-names
 2023-01-05_19:55:11.46515 webpack               : IncrementalWebpackCompiler: Currently compiling route entrypoints: 25 of 429
 2023-01-05_19:56:47.63851 webpack               : IncrementalWebpackCompiler: Have not visited pages.profiles.passwords.new recently. Adding to compilation.
 2023-01-05_19:57:18.58202 webpack               : Killed

最后

欢迎大家提 MR 维护这个文档
如有其它问题，请首先联系你的 buddy，或者加入 slack channel #gitlab-dev-env-setup 提问