# Gitlab Server

#### Installation

- [https://docs.gitlab.com/install/](https://docs.gitlab.com/install/)

##### With Docker

```bash
mkdir /mygitlab

docker run --detach \
  --hostname  mygit.example.com\
  --publish 80:80 \
  --name gitlab \
  --volume /mygitlab/config:/etc/gitlab \
  --volume /mygitlab/logs:/var/log/gitlab \
  --volume /mygitlab/data:/var/opt/gitlab \
  --rm \
  gitlab/gitlab-ce:17.11.7-ce.0
```

#### Config

- [https://docs.gitlab.com/administration/](https://docs.gitlab.com/administration/)

重要檔案與目錄路徑：

- 主設定檔：`/etc/gitlab/gitlab.rb`
- 所有子服務日誌檔：`/var/log/gitlab/*`
- 系統密鑰檔：`/etc/gitlab/gitlab-secrets.json`

##### Custom port

- [https://docs.gitlab.com/install/docker/configuration/#expose-gitlab-on-different-ports](https://docs.gitlab.com/install/docker/configuration/#expose-gitlab-on-different-ports)

1- docker command

- 使用非標準埠時，host 與 container 必須使用相同埠號。
- 如果只修改 docker 啟動參數的外部 port，而不修改 gitlab.rb，服務可以正常啟動，首頁與帳號登入也正常，不過網頁上的專案 URL 位址會不正確。

```bash
docker run --detach \
  --hostname 10.4.1.76 \
  --publish 6080:6080 \
  --name gitlab \
  --volume /myapp/gitlab/config:/etc/gitlab \
  --volume /myapp/gitlab/logs:/var/log/gitlab \
  --volume /myapp/gitlab/data:/var/opt/gitlab \
...
```

2- Edit `gitlab.rb`

- 變更 port 會影響 container 的通訊埠，且必須與 docker 啟動參數 --publish 的內部 port 相同。

```
nginx['listen_port'] = 6080
external_url 'http://10.4.1.76:6080'
```

##### LDAP (Windows AD)

- [https://docs.gitlab.com/administration/auth/ldap/](https://docs.gitlab.com/administration/auth/ldap/)

gitlab.rb :

```
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main: # 'main' is the GitLab 'provider ID' of this LDAP server
    label: 'LDAP'
    host: 'ad03.example.com'
    port: 389           # LDAP服务端口389，如果LDAP基于SSL在端口通常为636
    uid: 'sAMAccountName'   # LDAP中用戶名的對應屬性，通常為'sAMAccountName'
    bind_dn: 'yourdomain\your-ad-user' # 同步用户帳戶, 格式為 'domain\username'
    password: 'ThisIsPassword'     # 同步用户帳戶密碼
    encryption: 'plain'     # 'start_tls' or 'simple_tls' or 'plain'
    verify_certificates: false  # 如果使用SSL，則設定true
    active_directory: true    # 如果是 使用 Windows Active Directory LDAP server 設定為 true
    allow_username_or_email_login: false  # 是否允許Email登入
    lowercase_usernames: false            # 是否將用戶轉成小寫
    block_auto_created_users: True       # 是否自動建立帳號
    base: 'OU=YOURDOMAIN,DC=example,DC=com' # 搜索LDAP用户是的BaseDN
    user_filter: ''
EOS

```

##### SMTP

- [https://docs.gitlab.com/omnibus/settings/smtp/](https://docs.gitlab.com/omnibus/settings/smtp/)

#### gitlab-ctl commands

```bash
# Check the services
> gitlab-ctl status

run: alertmanager: (pid 820) 3073s; run: log: (pid 619) 3108s
run: gitaly: (pid 291) 3170s; run: log: (pid 309) 3169s
run: gitlab-exporter: (pid 799) 3075s; run: log: (pid 567) 3126s
run: gitlab-kas: (pid 452) 3158s; run: log: (pid 464) 3155s
run: gitlab-workhorse: (pid 791) 3075s; run: log: (pid 513) 3138s
run: logrotate: (pid 260) 3182s; run: log: (pid 268) 3181s
run: nginx: (pid 540) 3133s; run: log: (pid 550) 3132s
run: postgres-exporter: (pid 828) 3073s; run: log: (pid 738) 3100s
run: postgresql: (pid 316) 3164s; run: log: (pid 449) 3161s
run: prometheus: (pid 809) 3074s; run: log: (pid 606) 3112s
run: puma: (pid 467) 3152s; run: log: (pid 475) 3148s
run: redis: (pid 272) 3176s; run: log: (pid 288) 3173s
run: redis-exporter: (pid 801) 3074s; run: log: (pid 588) 3120s
run: sidekiq: (pid 479) 3145s; run: log: (pid 488) 3144s
run: sshd: (pid 36) 3192s; run: log: (pid 35) 3192s


> gitlab-ctl status postgresql
run: postgresql: (pid 316) 3748s; run: log: (pid 449) 3745s
```

```bash
# Reload the configuration
> gitlab-ctl reconfigure
```

```bash
# Restart the service puma
> gitlab-ctl restart puma

# Restart all services
> gitlab-ctl restart
```

#### Backup &amp; Restore

- [https://docs.gitlab.com/install/docker/backup/](https://docs.gitlab.com/install/docker/backup/)
- [https://docs.gitlab.com/administration/backup\_restore/](https://docs.gitlab.com/administration/backup_restore/)
- [遷移至新主機](https://docs.gitlab.com/administration/backup_restore/migrate_to_new_server/)

<p class="callout warning">注意：除了使用指令 gitlab-backup 以外，還需要另外備份系統目錄裡 /etc/gitlab 的兩個檔案  
1. gitlab.rb (主要設定檔)  
2. gitlab-secrets.json (系統密鑰檔) : 用來解密資料庫的資料</p>

With Docker

- 備份檔 (`編號_日期_版本_gitlab_backup.tar`) 要先複製到 container 的目錄 `/var/opt/gitlab/backups` (預設)

```bash
# Backup
docker exec -it <container-name> gitlab-backup create
# Backup DB only
docker exec -it <container-name> gitlab-backup create SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state

# Verify the backup file
docker exec -it <container-name> ls  /var/opt/gitlab/backups

# Restore
docker exec -it <container-name> bash
> gitlab-ctl stop puma
> gitlab-ctl stop sidekiq
> gitlab-ctl status

> gitlab-backup restore BACKUP=1704810663_2024_01_09_17.11.1
# Restore DB only
> gitlab-backup restore BACKUP=1704810663_2024_01_09_17.11.1 SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state

> gitlab-ctl restart
> gitlab-rake gitlab:check SANITIZE=true
> gitlab-rake gitlab:artifacts:check
> gitlab-rake gitlab:lfs:check
> gitlab-rake gitlab:uploads:check

# Restart the container
docker restart <container-name>
```

#### Upgrade &amp; Patch

- [Releases | GitLab](https://about.gitlab.com/releases/categories/releases/)
- [Release Managers | GitLab](https://about.gitlab.com/community/release-managers/)
- [Before you upgrade | GitLab Docs](https://docs.gitlab.com/update/plan_your_upgrade/)
- Upgrade 17.11 to 18: [https://docs.gitlab.com/update/versions/gitlab\_18\_changes/](https://docs.gitlab.com/update/versions/gitlab_18_changes/)

##### Pre-checks

- [https://docs.gitlab.com/update/upgrade/?tab=Docker#pre-upgrade-and-post-upgrade-checks](https://docs.gitlab.com/update/upgrade/?tab=Docker#pre-upgrade-and-post-upgrade-checks)

1- Check the general configuration:

```bash
# With Docker
docker exec -it <container-name> gitlab-rake gitlab:check | tee mylogs/check.250916.out
```

2- Confirm that encrypted database values can be decrypted:

<p class="callout warning">如果出現任何 failures 將會影響 Gitlab 的管理功能，請確定檔案 gitlab-secrets.json 是原始的版本，檔案內含有相關的密鑰，如果遺失，雖然系統仍可以透過備份檔回復，一般用戶也可以正常 pull/push 專案，但管理員將沒有權限操作大部分的網站管理功能。[參閱詳細資訊](https://docs.gitlab.com/administration/backup_restore/troubleshooting_backup_gitlab/#when-the-secrets-file-is-lost)</p>

```bash
# With Docker
docker exec -it <container-name> gitlab-rake gitlab:doctor:secrets | tee mylogs/doctor_secrets.250916.out
```

3- Check the status of all background database migrations.

```bash
gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

# With Docker
docker exec -it <container-name> gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
```

4- In GitLab UI, check that:

- Users can sign in.
- The project list is visible.
- Project issues and merge requests are accessible.
- Users can clone repositories from GitLab.
- Users can push commits to GitLab.

#### Post-installation

##### Disable Gravatar Service (optional)

Enter Admin Mode &gt; Settings &gt; General &gt; Account and limit

- Gravatar enabled: 不勾選

##### Container Log Rotation

如果使用 Docker 環境建置系統，在服務啟用後，container 的 log 檔在一段時間後可能會耗盡系統可用空間。要設定 container log 自動循環，啟動時需要增加幾個參數。

```bash
docker run --detach \
...
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
...

```

##### Health check

- [https://docs.gitlab.com/administration/monitoring/health\_check/](https://docs.gitlab.com/administration/monitoring/health_check/)
- Gitlab 支援 HTTP 協定的服務狀態檢測，方便外部的中央監控系統做監視。
- 預設不開放外部監控，需要手動將監控主機 IP 加入設定檔。
- 監控項目：基本服務/資料庫連線/Redis 快取

/etc/gitlab/gitlab.rb :

```
# IP allowlist endpoints
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '10.18.109.0/24']
```

套用設定

```bash
> gitlab-ctl reconfigure
```

HTTP GET

```
GET /health_check
GET /health_check/database
GET /health_check/cache
GET /health_check/migrations
```

#### Troubleshooting

##### Troubleshoot Tips

1. Check the container log： `docker logs -f <container-name>` ，檢視服務在啟動後的整個程序執行狀況。
2. Check the status of the services ： `gitlab-ctl status` ，注意每個服務的運行時間秒數，如果特定服務顯示特別短秒數，表示該服務異常且一直再重啟。
3. Check the nginx's log ： `/var/log/nginx/error.log` ，這裡可以查出是否有通訊埠衝突異常。

##### HTTP 502

1. 記憶體至少需要 4GB，如果不足可能無法初始化所有服務。
2. 通訊埠衝突，檢查 host 與 container 是否有相同 port 衝突。Gitlab 內建多個服務，啟動會開啟相應的 port，例如 puma 預設使用 8080。要檢查不同內建服務的預設 port 號，可以檢視 `gitlab.rb` 。

##### HTTP 500

- 變更 Admin 的參數設定時發生
- 檢查 `gitlab-secrets.json` (系統密鑰檔)是否與系統初始化時相同。