Triển khai GitLab CE Self-Hosted trên máy chủ On-Premises

#Triển khai GitLab CE Self-Hosted trên máy chủ On-Premises: Xây dựng nền tảng quản lý source code cho đội ngũ kỹ thuật

Danh mục: DevOps, Infrastructure, Software Engineering
Công nghệ: GitLab CE, Ubuntu Server, Linux, Git, SSH, HTTPS, Backup & Recovery

1. Bối cảnh và mục tiêu

Khi số lượng repository, thành viên và dự án tăng lên, việc quản lý source code cần một nền tảng tập trung thay vì phụ thuộc vào các quy trình phân tán.

GitLab Community Edition (CE) là một lựa chọn để tự triển khai hệ thống quản lý mã nguồn trên hạ tầng do tổ chức kiểm soát. Ngoài Git repository, GitLab còn cung cấp các chức năng như quản lý issue, merge request, phân quyền thành viên và tích hợp CI/CD.

Trong bài viết này, chúng ta xây dựng một GitLab CE instance trên máy chủ Ubuntu Server trong mạng nội bộ.

Mục tiêu triển khai:

• Tập trung repository của các dự án vào một nền tảng thống nhất.
• Quản lý thành viên và quyền truy cập theo group, project.
• Chuẩn hóa quy trình làm việc thông qua branch, merge request và code review.
• Tạo nền tảng để tích hợp CI/CD trong các giai đoạn tiếp theo.
• Chủ động kiểm soát hạ tầng, dữ liệu và quy trình backup, recovery.

Phạm vi bài viết tập trung vào cài đặt, cấu hình cơ bản và vận hành hệ thống. CI/CD Runner, High Availability và kiến trúc nhiều node sẽ được xem là các bước mở rộng riêng.

2. Kiến trúc triển khai

Với quy mô đội ngũ nhỏ hoặc trung bình, có thể bắt đầu bằng kiến trúc single-node để giảm độ phức tạp vận hành.

       Developer Workstations
          |             |
        HTTPS           SSH
          |             |
          +------+------+
                 |
          Internal Network
             / VPN
                 |
                 v
       +----------------------+
       |    Ubuntu Server     |
       |                      |
       |      GitLab CE       |
       |                      |
       |  Web UI / API        |
       |  Git over HTTPS      |
       |  Git over SSH        |
       |  PostgreSQL          |
       |  Redis / Sidekiq     |
       |  Gitaly              |
       +----------------------+
                 |
                 v
       Backup Storage
       Separate Destination

GitLab Linux package, còn gọi là Omnibus GitLab, đóng gói phần lớn các thành phần cần thiết để chạy GitLab vào một gói cài đặt. Đây là lựa chọn phù hợp khi cần triển khai và bảo trì một instance đơn giản trên Linux.

Tài liệu chính thức: https://docs.gitlab.com/install/package/

Vì sao chọn single-node?

Trong giai đoạn đầu, single-node giúp giảm số lượng thành phần cần quản lý, đơn giản hóa việc cài đặt, cập nhật và xử lý sự cố.

Đổi lại, đây là một điểm lỗi tập trung. Nếu máy chủ hoặc ổ đĩa gặp sự cố, nhiều dịch vụ phụ thuộc vào GitLab có thể bị gián đoạn cùng lúc.

Vì vậy, kiến trúc đơn node phù hợp để bắt đầu, nhưng không loại bỏ nhu cầu backup độc lập và kế hoạch phục hồi.

3. Chuẩn bị hạ tầng

3.1. Tài nguyên máy chủ

Tài nguyên cần thiết phụ thuộc vào số lượng người dùng, dung lượng repository, mức độ sử dụng CI/CD, artifacts và các dịch vụ chạy cùng máy chủ.

GitLab có thể chạy trong môi trường hạn chế tài nguyên với khoảng 8 GB RAM trong một số trường hợp, nhưng mức sử dụng thực tế và các tác vụ như upgrade, backup có thể đòi hỏi thêm tài nguyên. Không nên xem cấu hình tối thiểu là cấu hình tối ưu cho production.

Tham khảo: https://docs.gitlab.com/install/requirements/

3.2. Cập nhật hệ điều hành

Sau khi cài đặt Ubuntu Server, cập nhật package và cài đặt các công cụ cần thiết:

sudo apt update
sudo apt upgrade -y

sudo apt install -y curl openssh-server ca-certificates tzdata

Bật dịch vụ SSH để quản trị máy chủ:

sudo systemctl enable --now ssh

sudo systemctl status ssh

Nên sử dụng SSH key cho quản trị hệ thống, hạn chế đăng nhập SSH bằng mật khẩu và chỉ cho phép các tài khoản quản trị cần thiết truy cập máy chủ.

3.3. Thiết lập hostname và DNS

Giả sử hostname nội bộ của GitLab là:

gitlab.example.internal

Đây là hostname minh họa; khi triển khai thực tế, hãy thay bằng hostname phù hợp với DNS nội bộ.

Các máy developer phải phân giải hostname này về địa chỉ IP của máy chủ GitLab. Có thể sử dụng DNS nội bộ hoặc cấu hình tạm thời trong file hosts để kiểm thử.

Ví dụ trên Linux:

sudo nano /etc/hosts

Thêm dòng sau, thay địa chỉ IP minh họa bằng địa chỉ thực tế:

192.0.2.10 gitlab.example.internal

Địa chỉ 192.0.2.10 thuộc dải IP dành cho tài liệu minh họa, không phải địa chỉ để sử dụng trực tiếp trong mạng nội bộ.

Kiểm tra phân giải tên:

getent hosts gitlab.example.internal

Hostname nên được xác định trước khi cài đặt vì nó ảnh hưởng đến URL truy cập, cấu hình Git remote và TLS certificate.

4. Cài đặt GitLab Community Edition

GitLab cung cấp Linux package cho Community Edition. Với Ubuntu, nên sử dụng repository chính thức và package manager để cài đặt, thay vì tự ghép từng dịch vụ thành phần.

4.1. Thêm repository chính thức

Chạy script cài đặt repository CE:

curl --location \
  "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh" \
  | sudo bash

Trong môi trường production, nên xem xét nội dung script trước khi thực thi và đảm bảo máy chủ có thể truy cập repository cần thiết.

4.2. Cài đặt package

Với một instance nội bộ chưa cấu hình HTTPS, có thể sử dụng HTTP trong giai đoạn bootstrap và cấu hình TLS trước khi cho phép sử dụng thực tế.

sudo EXTERNAL_URL="http://gitlab.example.internal" \
  apt install -y gitlab-ce

Thay gitlab.example.internal bằng hostname đã thiết lập ở bước trước.

GitLab sẽ sử dụng giá trị EXTERNAL_URL để cấu hình địa chỉ truy cập của instance. Sau khi cài đặt, quá trình khởi tạo các thành phần có thể mất một khoảng thời gian.

Kiểm tra trạng thái:

sudo gitlab-ctl status

Nếu cần áp dụng lại cấu hình sau khi chỉnh sửa, sử dụng:

sudo gitlab-ctl reconfigure

4.3. Truy cập lần đầu

Mở URL đã cấu hình từ một máy có kết nối mạng phù hợp:

http://gitlab.example.internal

Với cài đặt Linux package mới, mật khẩu ban đầu của tài khoản root thường được lưu tại:

/etc/gitlab/initial_root_password

Đọc mật khẩu bằng quyền quản trị:

sudo cat /etc/gitlab/initial_root_password

File này được GitLab tự động xóa sau 24 giờ. Hãy đăng nhập, đổi mật khẩu ngay và lưu thông tin quản trị theo chính sách bảo mật phù hợp.

Không đưa mật khẩu này vào source code, tài liệu công khai hoặc repository.

Tài liệu cài đặt chính thức: https://docs.gitlab.com/install/package/ubuntu/

5. Cấu hình truy cập và bảo mật

Một instance GitLab đã cài đặt thành công chưa có nghĩa là đã sẵn sàng phục vụ đội ngũ.

Trước khi đưa vào sử dụng, cần xác định ai được truy cập, phương thức xác thực nào được sử dụng và những cổng mạng nào phải mở.

5.1. Giới hạn phạm vi mạng

Với GitLab nội bộ, có thể giới hạn quyền truy cập qua LAN hoặc VPN. Không nhất thiết phải công khai giao diện quản trị ra Internet.

Các cổng thường cần xem xét:

Không mở toàn bộ cổng chỉ để khắc phục lỗi kết nối. Cần xác định service nào đang lắng nghe và luồng mạng nào thực sự cần thiết.

5.2. Cấu hình HTTPS

HTTP chỉ phù hợp với bước bootstrap trong một mạng thử nghiệm được kiểm soát. Với hệ thống sử dụng thật, nên triển khai HTTPS bằng chứng thư được các máy client tin cậy.

Trong môi trường on-premises, có thể sử dụng:

• Chứng thư do hệ thống CA nội bộ cấp.
• Reverse proxy nội bộ đảm nhiệm TLS termination.
• Chứng thư công khai nếu hostname và kiến trúc mạng đáp ứng điều kiện tương ứng.

Không nên mặc định rằng Let's Encrypt sẽ cấp chứng thư cho một hostname chỉ tồn tại trong DNS nội bộ.

Sau khi cấu hình TLS, kiểm tra chứng thư, hostname, thời hạn và chuỗi tin cậy từ máy developer.

5.3. Quản lý tài khoản và quyền truy cập

Không nên dùng chung tài khoản root cho toàn bộ đội ngũ.

Mỗi thành viên nên có tài khoản riêng. Phân quyền theo nguyên tắc tối thiểu: chỉ cấp quyền cần thiết để thực hiện công việc.

Có thể tổ chức theo cấu trúc:

GitLab
├── Group: Product A
│   ├── Project: frontend
│   └── Project: backend
├── Group: Product B
│   ├── Project: web-app
│   └── Project: api
└── Group: Internal Tools
    └── Project: automation

Tên group và project ở trên chỉ mang tính minh họa.

Group giúp quản lý thành viên và quyền truy cập theo phạm vi công việc. Project chứa repository, issue, merge request và các cấu hình liên quan.

Khi tạo group hoặc project, cần xem xét visibility phù hợp, hạn chế quyền truy cập công khai nếu không có yêu cầu rõ ràng.

5.4. SSH key cho Git

Developer có thể tạo SSH key trên máy cá nhân:

ssh-keygen -t ed25519 -C "developer@example.com"

Sau đó thêm public key vào hồ sơ GitLab. Không chia sẻ private key và không tải private key lên máy chủ GitLab.

Kiểm tra kết nối:

ssh -T git@gitlab.example.internal

Nếu SSH sử dụng cổng khác cổng mặc định, cần chỉ định cổng tương ứng trong SSH client hoặc cấu hình GitLab.

6. Chuẩn hóa quy trình quản lý source code

Sau khi hạ tầng hoạt động, giá trị của GitLab phụ thuộc nhiều vào cách đội ngũ sử dụng nó.

Một quy trình đơn giản có thể bắt đầu như sau:

Issue
  |
  v
Feature Branch
  |
  v
Commit Changes
  |
  v
Merge Request
  |
  v
Code Review
  |
  v
Pipeline / Tests
  |
  v
Merge to Protected Branch

6.1. Quy ước branch

Có thể thống nhất một số quy ước cơ bản:

• main: nhánh ổn định.
• feature/*: phát triển tính năng.
• fix/*: sửa lỗi.
• hotfix/*: xử lý lỗi khẩn cấp trên môi trường production.

Tên branch cần thống nhất trong đội ngũ. Điều quan trọng hơn tên gọi là mọi người hiểu khi nào tạo branch, khi nào merge và cách xử lý xung đột.

6.2. Merge Request và code review

Thay vì đẩy trực tiếp mọi thay đổi lên nhánh chính, developer tạo merge request để mô tả mục tiêu, phạm vi thay đổi và kết quả kiểm thử.

Người review có thể kiểm tra:

• Tính đúng đắn của logic.
• Khả năng ảnh hưởng đến các chức năng hiện có.
• Rủi ro bảo mật.
• Chất lượng và khả năng bảo trì của code.
• Kết quả kiểm thử.

Với những repository quan trọng, nên cấu hình protected branch và yêu cầu phê duyệt trước khi merge. Cấu hình cụ thể cần phù hợp với phiên bản GitLab và chính sách phân quyền đang áp dụng.

6.3. Liên kết công việc với source code

Issue có thể được dùng để ghi nhận yêu cầu, lỗi hoặc công việc kỹ thuật. Merge request nên tham chiếu đến issue tương ứng để tạo mối liên hệ giữa mục tiêu công việc và thay đổi trong repository.

Nhờ đó, việc rà soát lịch sử phát triển không chỉ dừng ở câu hỏi “ai đã sửa code nào”, mà còn trả lời được “thay đổi này nhằm giải quyết vấn đề gì”.

7. Kiểm tra vận hành sau cài đặt

Trước khi chuyển sang sử dụng chính thức, cần kiểm tra các thành phần chính và thực hiện một vòng thử nghiệm từ máy developer.

7.1. Kiểm tra trạng thái dịch vụ

sudo gitlab-ctl status

Xem log tổng hợp:

sudo gitlab-ctl tail

Nếu một service gặp sự cố, hãy kiểm tra log liên quan trước khi khởi động lại toàn bộ hệ thống.

7.2. Kiểm tra tài nguyên

free -h
df -h
uptime

Các lệnh này giúp kiểm tra RAM, dung lượng lưu trữ và tải trung bình của máy chủ.

Cần đặc biệt theo dõi dung lượng phân vùng chứa repository, database, logs và dữ liệu backup. Hệ thống có thể hoạt động bình thường trong thời gian dài rồi gặp sự cố khi ổ đĩa đầy.

7.3. Kiểm thử luồng Git end-to-end

Tạo một project thử nghiệm, sau đó thực hiện đầy đủ các thao tác:

1. Clone repository từ máy developer.
2. Tạo branch và commit một thay đổi.
3. Push branch lên GitLab.
4. Tạo merge request.
5. Review và merge theo quy trình đã thiết lập.
6. Kiểm tra lịch sử commit và quyền truy cập bằng tài khoản khác.

Đây là bước quan trọng để xác nhận không chỉ giao diện web hoạt động, mà cả luồng Git và quyền truy cập cũng đúng với thiết kế.

8. Backup và khôi phục dữ liệu

Repository là tài sản quan trọng, nhưng dữ liệu cần bảo vệ không chỉ có source code.

Một GitLab instance còn có database, cấu hình, thông tin xác thực, uploads và những dữ liệu phụ trợ khác.

8.1. Tạo backup

Với GitLab cài bằng Linux package, lệnh tạo backup cơ bản là:

sudo gitlab-backup create

Backup mặc định được lưu trong thư mục backup được cấu hình của GitLab, thường là:

/var/opt/gitlab/backups

Tuy nhiên, backup của GitLab không tự động bao gồm mọi dữ liệu ở mọi cấu hình, đặc biệt khi có sử dụng object storage bên ngoài.

8.2. Bảo vệ cấu hình và secret

Ngoài archive backup, cần có quy trình bảo vệ các file cấu hình quan trọng, đặc biệt là:

/etc/gitlab/gitlab.rb
/etc/gitlab/gitlab-secrets.json

Các file này có thể chứa cấu hình nhạy cảm hoặc thông tin cần thiết để khôi phục một số dữ liệu đã mã hóa. Phải giới hạn quyền truy cập và mã hóa khi lưu trữ bên ngoài.

8.3. Lưu backup ở một nơi khác

Không nên chỉ lưu bản backup trên chính ổ đĩa vật lý đang chạy GitLab.

Nếu máy chủ hoặc ổ đĩa gặp sự cố nghiêm trọng, cả dữ liệu chính lẫn bản backup có thể mất cùng lúc.

Nên chuyển bản backup đến một đích lưu trữ độc lập, thiết lập lịch chạy, chính sách lưu giữ và kiểm tra tính toàn vẹn.

8.4. Kiểm thử restore

Backup chỉ có ý nghĩa khi có thể khôi phục.

Quy trình restore cần sử dụng phiên bản và loại GitLab tương thích với bản backup. Cần kiểm tra tài liệu tương ứng với phiên bản đang triển khai, đặc biệt nếu có các thay đổi về schema hoặc quy trình nâng cấp.

Một bài kiểm thử restore nên xác nhận:

• Repository và commit history được phục hồi.
• Tài khoản, group và project có thể truy cập.
• Cấu hình và dữ liệu cần thiết vẫn còn nguyên vẹn.
• Người dùng có thể clone, push và thực hiện các thao tác cơ bản sau khôi phục.

Tài liệu chính thức:

• Backup: https://docs.gitlab.com/administration/backup_restore/backup_gitlab/
• Restore: https://docs.gitlab.com/administration/backup_restore/restore_gitlab/

9. Hướng mở rộng

Sau khi hệ thống single-node ổn định, có thể mở rộng theo nhu cầu thực tế.

Tích hợp CI/CD Runner: Tách workload build và test khỏi máy chủ GitLab. Runner cần được quản lý riêng về quyền truy cập, tài nguyên và mức độ cô lập job.

Chuẩn hóa release: Xây dựng pipeline kiểm thử, build Docker image, gắn tag phiên bản và triển khai artifact đã kiểm chứng.

Monitoring và cảnh báo: Theo dõi tài nguyên máy chủ, thời gian phản hồi, dung lượng ổ đĩa và tình trạng các dịch vụ.

Quản lý vòng đời: Lập lịch cập nhật GitLab, kiểm tra upgrade path, đọc release notes và thực hiện backup trước khi nâng cấp.

Khả năng sẵn sàng cao: Nếu yêu cầu downtime thấp hoặc số lượng người dùng tăng đáng kể, cần đánh giá kiến trúc HA và các phương án triển khai phân tán. Không nên bổ sung độ phức tạp này trước khi xác định rõ yêu cầu về tải và khả năng phục hồi.

Kết luận

Triển khai GitLab CE on-premises không chỉ là cài đặt một ứng dụng quản lý Git. Đây là quá trình xây dựng một dịch vụ hạ tầng phục vụ vòng đời phát triển phần mềm.

Một hệ thống có giá trị khi repository được quản lý tập trung, quyền truy cập được kiểm soát, quy trình review rõ ràng và dữ liệu có thể phục hồi khi xảy ra sự cố.

Bắt đầu bằng một kiến trúc single-node phù hợp giúp giảm độ phức tạp ban đầu. Nhưng để sử dụng lâu dài, cần xem bảo mật, backup, monitoring và nâng cấp là những phần không thể tách rời khỏi quá trình triển khai.

Mục tiêu cuối cùng không chỉ là tự quản lý source code, mà là xây dựng một nền tảng kỹ thuật có thể vận hành ổn định và phát triển cùng đội ngũ.