Cài Jenkins trên Linux

Mục lụcCopy Anchor Link

• 1. Chọn Jenkins LTS và Java
  • 1.1 Chọn Jenkins LTS
  • 1.2 Chọn Java 21
• 2. Yêu cầu hệ thống và chuẩn bị
  • 2.1 Tài nguyên phần cứng
  • 2.2 Điều kiện trước khi cài
• 3. Cài Jenkins từ repository chính thức
• 4. Khởi động và mở cổng 8080
  • 4.1 Khởi động service
  • 4.2 Cấu hình firewall
  • 4.3 Xác minh Jenkins đang lắng nghe
• 5. Unlock Jenkins và hoàn tất thiết lập
• 6. Vận hành service và đường dẫn quan trọng
  • 6.1 Các lệnh systemd thường dùng
  • 6.2 Các đường dẫn cần biết
  • 6.3 Thay đổi cổng bằng systemd override
• 7. Cập nhật Jenkins an toàn
• 8. Gỡ cài đặt
• 9. Hardening cơ bản cho production
• 10. Troubleshooting
  • 10.1 Jenkins không khởi động
  • 10.2 Lỗi repository hoặc signing key
  • 10.3 Truy cập từ xa thất bại
  • 10.4 Hết dung lượng hoặc lỗi quyền
• 11. Bước tiếp theo
• Checklist hoàn thành
• Tài liệu tham khảo

1. Chọn Jenkins LTS và JavaCopy Anchor Link

1.1 Chọn Jenkins LTSCopy Anchor Link

Jenkins phát hành theo hai release line:

Hướng dẫn này dùng repository debian-stable và rpm-stable. Package manager sẽ cài bản LTS hiện hành từ Jenkins, nên không cần hard-code số phiên bản vào lệnh.

1.2 Chọn Java 21Copy Anchor Link

Jenkins chạy trên Java, nhưng Java dùng để chạy controller không bắt buộc phải giống JDK dùng để build ứng dụng. Theo hướng dẫn cài Linux hiện hành của Jenkins, hãy dùng OpenJDK 21 làm runtime mặc định.

Kiểm tra Java sau khi cài:

java -version

Kết quả phải cho thấy major version 21. Không tiếp tục nếu lệnh không tồn tại hoặc đang trỏ tới một Java không được phiên bản Jenkins đích hỗ trợ.

2. Yêu cầu hệ thống và chuẩn bịCopy Anchor Link

2.1 Tài nguyên phần cứngCopy Anchor Link

Mức tối thiểu chính thức chỉ phù hợp để Jenkins khởi động:

• RAM: 256 MB;
• dung lượng đĩa: 1 GB.

Với một nhóm nhỏ, Jenkins khuyến nghị điểm khởi đầu:

• RAM: 4 GB trở lên;
• dung lượng đĩa: 50 GB trở lên.

Dung lượng thực tế phụ thuộc số plugin, job, build history và artifact. Controller production nên dành tài nguyên cho điều phối, giao diện và lưu cấu hình. Không chạy workload build nặng trực tiếp trên controller; hãy dùng agent riêng.

2.2 Điều kiện trước khi càiCopy Anchor Link

Máy chủ cần có:

• bản Linux 64-bit còn được nhà cung cấp hỗ trợ;
• systemd;
• tài khoản có quyền sudo;
• DNS và kết nối HTTPS ra pkg.jenkins.io;
• port TCP 8080 chưa bị process khác chiếm;
• đồng hồ hệ thống đồng bộ;
• đủ dung lượng cho /var/lib/jenkins;
• một trình duyệt trên máy quản trị để hoàn tất setup wizard.

Kiểm tra nhanh hệ điều hành, kiến trúc, bộ nhớ, đĩa và port:

cat /etc/os-release
uname -m
free -h
df -h /var/lib 2>/dev/null || df -h /
sudo ss -ltnp | grep ':8080' || true

Nếu dòng cuối không in kết quả, thường chưa có process lắng nghe trên port 8080.

3. Cài Jenkins từ repository chính thứcCopy Anchor Link

Chọn đúng tab cho hệ điều hành. Các lệnh chỉ cấu hình LTS repository chính thức.

sudo apt update
sudo apt install fontconfig openjdk-21-jre wget
java -version

sudo install -m 0755 -d /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
  https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
sudo chmod 0644 /etc/apt/keyrings/jenkins-keyring.asc

echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" \
  | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

5E38 6EAD B55F 0150 4CAE  8BCF 7198 F4B7 14AB FC68

sudo apt update
apt-cache policy jenkins
sudo apt install jenkins

Sau khi cài, package tạo user hệ thống jenkins, khai báo service jenkins.service, đặt JENKINS_HOME mặc định tại /var/lib/jenkins và cấu hình HTTP port mặc định là 8080.

4. Khởi động và mở cổng 8080Copy Anchor Link

4.1 Khởi động serviceCopy Anchor Link

Bật Jenkins ngay bây giờ và tự động khởi động cùng hệ điều hành:

sudo systemctl enable --now jenkins
sudo systemctl is-enabled jenkins
sudo systemctl is-active jenkins

Kết quả mong đợi của hai lệnh cuối là enabled và active. Xem trạng thái chi tiết nếu service chưa chạy:

sudo systemctl status jenkins --no-pager --full
sudo journalctl -u jenkins.service -n 100 --no-pager

4.2 Cấu hình firewallCopy Anchor Link

Chỉ chạy tab tương ứng nếu firewall đó đang được sử dụng.

sudo ufw status verbose
sudo ufw allow 8080/tcp
sudo ufw status numbered

Nếu máy chạy trên cloud, còn phải cấu hình security group, network security rule hoặc firewall bên ngoài máy chủ.

Jenkins còn có TCP port cho inbound agent, nhưng không cần mở port đó để hoàn thành bài này. Chỉ mở khi bạn đã cấu hình một port cố định và thực sự dùng inbound TCP agent.

4.3 Xác minh Jenkins đang lắng ngheCopy Anchor Link

Trên server:

sudo ss -ltnp | grep ':8080'

Nếu có curl, kiểm tra HTTP cục bộ:

curl --head http://127.0.0.1:8080/login

Sau đó mở một trong các URL sau trên trình duyệt:

http://localhost:8080
http://SERVER_IP:8080

Dùng localhost khi trình duyệt chạy cùng server. Với máy khác, thay SERVER_IP bằng IP hoặc DNS của Jenkins server.

5. Unlock Jenkins và hoàn tất thiết lậpCopy Anchor Link

Ở lần khởi động đầu tiên, Jenkins tạo một mật khẩu dùng một lần trong JENKINS_HOME. Đọc mật khẩu trên terminal tin cậy:

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Hướng dẫn chi tiết tiếp tục ở trang Thiết lập ban đầu.

6. Vận hành service và đường dẫn quan trọngCopy Anchor Link

6.1 Các lệnh systemd thường dùngCopy Anchor Link

Package Linux hiện đại ghi console log vào systemd-journald. Vì vậy, hãy dùng journalctl thay vì mặc định đi tìm /var/log/jenkins/jenkins.log.

6.2 Các đường dẫn cần biếtCopy Anchor Link

systemctl cat jenkins là nguồn chính xác nhất để biết unit file và giá trị đang áp dụng trên chính máy của bạn.

6.3 Thay đổi cổng bằng systemd overrideCopy Anchor Link

Ví dụ đổi HTTP port từ 8080 sang 8081:

sudo systemctl edit jenkins

Nhập nội dung:

[Service]
Environment="JENKINS_PORT=8081"

Lưu file, sau đó áp dụng và kiểm tra:

sudo systemctl restart jenkins
sudo systemctl status jenkins --no-pager --full
sudo ss -ltnp | grep ':8081'

Đồng thời cập nhật firewall, reverse proxy, health check và Jenkins URL. systemctl edit tự reload unit; nếu tự tạo drop-in bằng công cụ khác, chạy sudo systemctl daemon-reload trước khi restart.

7. Cập nhật Jenkins an toànCopy Anchor Link

Không cập nhật controller production như một package độc lập mà bỏ qua Java, plugin và khả năng rollback. Quy trình tối thiểu:

1. đọc LTS changelog, LTS Upgrade Guide và Java Support Policy;
2. kiểm tra plugin quan trọng tương thích với bản đích;
3. thông báo maintenance window và dừng nhận build mới;
4. backup toàn bộ /var/lib/jenkins, bao gồm secret, rồi kiểm tra khả năng restore;
5. ghi lại package version, Java version và danh sách plugin hiện tại;
6. cập nhật trên staging trước nếu Jenkins phục vụ workload quan trọng;
7. cập nhật package, theo dõi log và chạy smoke test;
8. chỉ nâng plugin theo kế hoạch đã kiểm thử.

Kiểm tra version trước khi cập nhật:

java -version
jenkins --version
sudo systemctl status jenkins --no-pager

sudo apt update
apt-cache policy jenkins
sudo apt install --only-upgrade jenkins
sudo systemctl status jenkins --no-pager --full

Sau nâng cấp, kiểm tra:

jenkins --version
sudo journalctl -u jenkins.service -n 200 --no-pager

Sau đó xác nhận đăng nhập, queue, agent connection, credential integration và một Pipeline đại diện đều hoạt động.

Xem quy trình đầy đủ tại Nâng cấp Jenkins.

8. Gỡ cài đặtCopy Anchor Link

Trước khi gỡ, backup /var/lib/jenkins nếu có khả năng cần khôi phục job, credential hoặc lịch sử build.

sudo systemctl disable --now jenkins
sudo apt remove jenkins

Lệnh gỡ package không phải là quy trình xóa dữ liệu an toàn. Sau khi gỡ, kiểm tra riêng các vị trí sau trước khi quyết định lưu trữ hoặc xóa:

sudo test -d /var/lib/jenkins && sudo du -sh /var/lib/jenkins
sudo test -d /etc/systemd/system/jenkins.service.d \
  && sudo ls -la /etc/systemd/system/jenkins.service.d

Repository cũng là cấu hình riêng. Chỉ xóa file repository/key nếu máy không còn dùng Jenkins và chính sách vận hành yêu cầu. Không chạy lệnh xóa đệ quy với /var/lib/jenkins cho đến khi đã xác nhận backup, đúng đường dẫn và đúng server.

9. Hardening cơ bản cho productionCopy Anchor Link

Checklist tối thiểu trước khi đưa controller vào sử dụng thật:

• Không public port 8080. Chỉ cho reverse proxy hoặc mạng quản trị truy cập.
• Bật HTTPS. Terminate TLS tại reverse proxy/load balancer và cấu hình forwarded headers đúng.
• Giữ authentication và authorization. Tắt anonymous access nếu không có yêu cầu rõ ràng; cấp quyền theo nguyên tắc tối thiểu.
• Không dùng chung admin account. Tích hợp identity provider phù hợp và giữ tài khoản khôi phục được kiểm soát.
• Không chạy build trên controller. Đặt executor của built-in node về 0, dùng agent tách biệt.
• Cài ít plugin nhất có thể. Gỡ plugin không dùng và theo dõi security advisory.
• Cập nhật có kiểm thử. Vá OS, Java, Jenkins core và plugin theo maintenance window.
• Backup và restore. Mã hóa bản sao JENKINS_HOME, lưu ngoài server và diễn tập khôi phục.
• Bảo vệ secret. Không đặt password/token trong command line, job log, repository hoặc systemd unit có quyền đọc quá rộng.
• Giám sát. Theo dõi service, disk/inode, heap, queue, executor, agent và lỗi đăng nhập.
• Giới hạn outbound network. Chỉ cho controller/agent truy cập package, plugin, SCM và dịch vụ thực sự cần.
• Không tắt SELinux để chữa lỗi. Đọc AVC denial và bổ sung policy tối thiểu nếu cần.

Khi đặt reverse proxy cùng máy, có thể bind Jenkins vào loopback bằng systemd override:

sudo systemctl edit jenkins

[Service]
Environment="JENKINS_OPTS=--httpListenAddress=127.0.0.1"

Nếu đã có JENKINS_OPTS, hãy giữ các option hiện tại trên cùng dòng thay vì ghi đè mất chúng. Sau thay đổi:

sudo systemctl restart jenkins
sudo ss -ltnp | grep ':8080'

Kết quả phải cho thấy Jenkins chỉ lắng nghe trên 127.0.0.1:8080. Cấu hình reverse proxy trước để tránh mất đường truy cập.

10. TroubleshootingCopy Anchor Link

Bắt đầu bằng bốn lệnh sau thay vì đoán:

sudo systemctl status jenkins --no-pager --full
sudo journalctl -u jenkins.service -b -n 200 --no-pager
java -version
sudo systemctl cat jenkins

10.1 Jenkins không khởi độngCopy Anchor Link

Sau mỗi thay đổi:

sudo systemctl restart jenkins
sudo systemctl is-active jenkins
sudo journalctl -u jenkins.service -n 100 --no-pager

10.2 Lỗi repository hoặc signing keyCopy Anchor Link

Với Debian/Ubuntu, xác nhận URL và key file:

cat /etc/apt/sources.list.d/jenkins.list
sudo ls -l /etc/apt/keyrings/jenkins-keyring.asc
sudo apt update

Source phải dùng debian-stable, signed-by và HTTPS. Nếu key cũ/hỏng, tải lại từ trang package chính thức. Không bỏ signed-by để né lỗi.

Với RHEL/Fedora:

cat /etc/yum.repos.d/jenkins.repo
sudo dnf clean expire-cache
sudo dnf makecache --refresh

Giữ gpgcheck=1 và repo_gpgcheck=1. Nếu fingerprint từ repository không khớp nguồn Jenkins chính thức, dừng cài đặt và xác minh lại DNS, proxy, URL cùng thông báo đổi key của Jenkins.

10.3 Truy cập từ xa thất bạiCopy Anchor Link

Chẩn đoán theo thứ tự:

1. systemctl is-active jenkins phải trả active;
2. curl --head http://127.0.0.1:8080/login phải nhận phản hồi HTTP;
3. ss phải cho thấy Jenkins bind đúng địa chỉ;
4. firewall trên server phải cho phép nguồn quản trị;
5. security group, ACL, load balancer và route bên ngoài phải cho phép kết nối;
6. reverse proxy phải chuyển đúng host, port và forwarded headers.

Nếu local truy cập được nhưng remote không được, Jenkins thường đã chạy; lỗi nằm ở bind address hoặc lớp mạng/firewall. Không tắt toàn bộ firewall để kiểm tra trên production.

10.4 Hết dung lượng hoặc lỗi quyềnCopy Anchor Link

Kiểm tra filesystem và inode:

df -h /var/lib/jenkins
df -i /var/lib/jenkins
sudo du -xhd1 /var/lib/jenkins | sort -h
sudo ls -ld /var/lib/jenkins
sudo namei -l /var/lib/jenkins

Các nguyên nhân thường gặp:

• build history hoặc artifact tăng không giới hạn;
• workspace/cache nằm trên controller;
• backup được ghi vào cùng filesystem rồi làm đầy đĩa;
• restore bằng root làm sai owner;
• mount chứa JENKINS_HOME chưa sẵn sàng khi service khởi động.

Không chạy chown -R theo phản xạ. Trước tiên xác định file nào sai owner và vì sao. Package mặc định chạy service bằng user jenkins; quyền thực tế có thể xem bằng:

sudo systemctl show jenkins --property=User,Group,Environment

Nếu SELinux chặn truy cập, đọc denial thay vì tắt SELinux:

sudo ausearch -m AVC -ts recent

11. Bước tiếp theoCopy Anchor Link

Sau khi service ổn định và bạn đã truy cập được trang unlock, tiếp tục theo thứ tự:

Checklist hoàn thànhCopy Anchor Link

• Đã chọn Jenkins LTS và cài Java 21 trước Jenkins.
• Repository trỏ đúng debian-stable hoặc rpm-stable qua HTTPS.
• Signing key có fingerprint đúng và kiểm tra chữ ký không bị tắt.
• jenkins.service ở trạng thái enabled và active.
• Jenkins lắng nghe trên port dự kiến.
• Firewall chỉ cho phép phạm vi cần thiết.
• Đã đọc initialAdminPassword trên terminal tin cậy và tạo admin user riêng.
• Biết dùng journalctl và systemctl cat jenkins để chẩn đoán.
• Đã xác định chiến lược backup/restore cho /var/lib/jenkins.
• Production có kế hoạch HTTPS, least privilege, agent riêng và cập nhật định kỳ.

Tài liệu tham khảoCopy Anchor Link

• Jenkins — Installing Jenkins on Linux
• Jenkins Debian LTS Packages
• Jenkins RPM LTS Packages
• Jenkins Java Support Policy
• Jenkins Linux Support Policy
• Jenkins Managing systemd Services
• Jenkins Hardware Recommendations
• Jenkins Securing Jenkins
• Jenkins LTS Upgrade Guide