安装开发环境帮助文档

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

gitlab-development-kit doc

前期准备

MacOS

请确保以下工具正确安装

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

请注意:

  1. 不要把 gdk repo 放到嵌套太深的文件夹中,因为后期会用到一些 socket 文件,而 socket 文件有 100 字符的限制,嵌套太深的文件夹很容易超出限制导致报错,推荐放到类似 /Users/xxx/work/gdk
  2. 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 源

类似下面的效果

git repo

我们执行完 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 目录中),需要注意:

  1. 因为 gitlab/jh 文件夹下有极狐自己用的 Gemfile,所以在启动 rails server 的时候,如果发现有类似“找不到 tencentcloud-sdk-common gem” 的错误,需要在 gitlab/.bundle/config 里面添加BUNDLE_GEMFILE: "jh/Gemfile",保证 jh/Gemfile 能正确加载
  2. 在执行 gdk update 的时候,当在 gitlab 目录下切换至 master 分支时,确保该目录中没有 jh 子目录。原因是在 gdk update 的时候需要确保没有任何 极狐 的代码被执行,也需要注释掉在 gitlab/.bundle/config 里面BUNDLE_GEMFILE: "jh/Gemfile", 确保 gdk update 顺利完成。可以添加下面的 bash_function 到你的 shell 中,通过 jh_gemfilegl_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"
}
  1. 对于第2点,除了使用上述 sh 脚本手动切换外,也可使用 git hook 在切换分支时自动处理好BUNDLE_GEMFILE配置:

    1. 检查自己~/.gitconfig里的templatedir配置的目录,比如是 templatedir = ~/.git_template

    2. 把如下script内容

      pwd=$(pwd)
      current_dir=$(basename $pwd)
      if [ $current_dir == 'gdk' ] || [ $current_dir == 'gitlab' ]; then
      	if [[ -d gitlab ]]; then
      		bundle_file="./gitlab/.bundle/config"
      	else
      		bundle_file="./.bundle/config"
      	fi
      
      	GEMFILE="jh/Gemfile"
           if [[ -f "$GEMFILE" ]] || [[ -f "gitlab/$GEMFILE"  ]]; then
      		echo "---\nBUNDLE_SET: \"without production\"\nBUNDLE_JOBS: \"5\"\nBUNDLE_GEMFILE: \"$GEMFILE\"" >$bundle_file
      		echo "ADD $GEMFILE in bundle/config"
      	else
      		echo '---\nBUNDLE_SET: "without production"\nBUNDLE_JOBS: "5"\n' >$bundle_file
      		echo "REMOVE $GEMFILE in bundle/config"
      	fi
      fi
      

      加入到第1步中确定的~/.git_template/hooks/post-checkout文件内,或者加入到项目下的:gitlab/.git/hooks/post-checkout文件内,即可。

      注意:上面两种方式都可行,区别在于后者只影响 gitlab 目录自身,前者是全局配置,会影响到你 HOME 目录下所有 git 目录。还有一点要小心,前者的全局git hook中如果加入了其他内容,在 gitlab 目录下执行切换分支的操作时,全局hook配置会自动同步写入项目下的hook。

  2. 完工。去gdk/gitlab目录下切换分支试试看吧。

设置本地网络

当前是使用 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 的:

  1. 使用 rubymine 打开 gitlab repo,注意不是 gdk repo
  2. 选择 Edit Configuration,

edit config

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

Debug GitLab Rails Server

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

  1. 暂停 gdk 管理的 rails 服务,gdk stop rails-web
  2. 打开 rubymine,选择 Edit Configuration(类似“运行本地测试”章节)
  3. 新增一个 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
    

set variable

  1. 选择刚才添加的启动项,点击 debug 即可,

start debug

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

使用 Table+ 查看数据库

不会连接数据库的程序员不是好程序员:)

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

table+

运行功能测试

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

常见问题收集

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

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

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

    手动执行它,才看到了缺少 view_componentpg 的依赖:

     $ 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.
    
  3. 安装 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)
    
  4. 报错 local error: tls: bad record MAC
    如果你用 ClashX Pro,记得打开增强模式(其他代理工具类似),否则可能出现某些请求不走代理的情况,会报此错误。

  5. 报错 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

  6. 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
    
  7. 国内源代理的影响

    #### Ruby

    务必注释掉~/.bundle/confg下的设置:

     // BUNDLE_MIRROR__HTTPS://RUBYGEMS__ORG/: "https://gems.ruby-china.com"
    

    否则会报类似这样的错误:

     Fetching source index from https://gems.ruby-china.com/
     Your bundle is locked to rails (6.1.7.1) from rubygems repository
     https://rubygems.org/ or installed locally, but that version can no longer be
     found in that source. That means the author of rails (6.1.7.1) has removed it.
     You'll need to update your bundle to a version other than rails (6.1.7.1) that
     hasn't been removed in order to install.
     make: *** [.gitlab-bundle] Error 7
     ❌️ ERROR: Failed to install.
    

    #### Go

    务必注释掉~/.zshrc等 shell 配置中的``GOPROXY`的设置:

     # export GOPROXY=https://mirrors.aliyun.com/goproxy/
    

    否则会报类似这样的错误:

     go: downloading go.opencensus.io v0.23.0
     go: downloading github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da
     internal/gitaly/gitaly.go:12:2: gitlab.com/gitlab-org/gitaly/v15@v15.4.0-rc2: reading https://mirrors.aliyun.com/goproxy/gitlab.com/gitlab-org/gitaly/v15/@v/v15.4.0-rc2.zip: 404 Not Found
     internal/gitaly/gitaly.go:13:2: gitlab.com/gitlab-org/gitaly/v15@v15.4.0-rc2: reading https://mirrors.aliyun.com/goproxy/gitlab.com/gitlab-org/gitaly/v15/@v/v15.4.0-rc2.zip: 404 Not Found
     internal/gitlabnet/accessverifier/client.go:8:2: gitlab.com/gitlab-org/gitaly/v15@v15.4.0-rc2: reading https://mirrors.aliyun.com/goproxy/gitlab.com/gitlab-org/gitaly/v15/@v/v15.4.0-rc2.zip: 404 Not Found
     make[1]: *** [bin/gitlab-shell] Error 1
     make: *** [gitlab-shell-setup] Error 2
     ❌️ ERROR: Failed to install.
    
  8. main-jh 分支安装Gem报错

    #### gpgme 安装报错

    报类似如下错误:

     gpgme gem uses locally built versions of required C libraries,
     namely libgpg-error, libassuan, and gpgme.
    

    解决方法:执行如下命令,然后再bundle install

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

    #### rugged 安装报错

    报类似如下错误:

     clang: error: no such file or directory: ':-L/opt/homebrew/opt/libffi/lib'
    

    解决方法:修改之前加入~/.zshrc等shell配置中的如下设置

     export LDFLAGS="$LDFLAGS:-L$(brew --prefix)/opt/libffi/lib"
     改为
     export LDFLAGS="-L$(brew --prefix)/opt/libffi/lib"
    

    然后再bundle install

最后

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