01Installation, Configuration and Routine Maintenance of Jenkins #
Jenkins是一个开源的自动化服务器，可以帮助开发者实现持续集成和交付。本文将介绍Jenkins的安装配置和日常维护。
安装Jenkins #
- 下载Jenkins的最新稳定版本（war包）：https://jenkins.io/zh/download/
- 在命令行中执行以下命令启动Jenkins：
Jenkins将在默认端口8080上启动。java -jar jenkins.war
首次访问Jenkins #
- 打开浏览器，访问http://localhost:8080。
- 安装插件：选择"Install suggested plugins"，等待插件安装完成。
- 创建管理员账号：填写管理员账号的用户名和密码，并保存凭据。
配置Jenkins #
- 自定义Jenkins主页：在管理页面中，选择"Configure System"，设置Jenkins的URL和名称。
- 配置全局工具：在管理页面中，选择"Global Tool Configuration"，添加Java、Git等工具的路径。
- 设置全局环境变量：在管理页面中，选择"Configure System"，设置全局环境变量（如JAVA_HOME）。
创建和配置项目 #
- 创建一个新项目：在Jenkins主页中，选择"New Item"，输入项目名称并选择项目类型。
- 配置项目：根据项目类型，配置相关构建步骤、源码管理和构建触发器等。
- 构建报告和控制台输出：在项目页面中，查看构建报告和控制台输出以检查构建结果。
定时构建任务 #
- 配置触发器：在项目的配置页面中，选择"Build Triggers"，设置定时触发构建的时间表达式。
- 多节点构建：在项目的配置页面中，选择"Restrict where this project can be run"，配置可以运行该项目的节点。
配置邮件通知 #
- 安装"Email Extension"插件：在插件管理页面中，搜索并安装"Email Extension"插件。
- 配置邮件通知：在项目的配置页面中，选择"Post-build Actions"，添加"Editable Email Notification"构建后操作。
日常维护 #
- 定期备份Jenkins数据：备份Jenkins的home目录，包括配置和插件。
- 插件更新和升级：定期检查插件的更新和升级，确保使用的插件是最新的稳定版本。
- 日志管理：定期清理构建日志和系统日志，以节省磁盘空间。
希望本文能够帮助您安装配置和维护Jenkins。如有任何问题，请随时向我们提问。
Jenkins Installation and System Management #
This chapter is the first article in the series “< >”. It mainly introduces the installation and configuration of the continuous integration tool, Jenkins, as well as some system management instructions for maintaining Jenkins. This continuous delivery/deployment tutorial primarily focuses on Jenkins and its integration with various open-source tools. Let’s begin with the introduction to this chapter’s content.
This section mainly covers the following topics:
- Jenkins installation
- Jenkins system management and basic configuration
Introduction #
Before we proceed with the formal installation of Jenkins, let’s first understand what Jenkins is.
Jenkins is a open-source, extensible continuous integration tool written in Java. It enables continuous integration and delivery projects, and can handle any type of integration build or deployment operation through various extension plugins.
Jenkins provides continuous integration services for software development. Continuous integration (CI) has become a necessary process for many development teams to ensure code quality throughout the software lifecycle. It is a practice aimed at mitigating and stabilizing the software build process, and Jenkins makes continuous integration possible. Its main objective is to monitor the software development process, quickly identify and report issues. With its rich and numerous extension plugins, Jenkins can assist development, operations, and QA teams in collaborating effectively in the entire CI/CD process, including software testing (interface testing, unit testing, etc.), software build (maven, ant, gradle), and software deployment (shell, docker, ansible, etc.), thereby improving work efficiency.
Installation #
After understanding what Jenkins is, let’s install Jenkins. The installation of Jenkins is relatively simple and can be done using war packages, rpm packages, Docker, etc. Here, we will briefly introduce two installation methods. Although the installation methods are different, the access methods and configurations are the same. Therefore, choose the installation method according to personal preference and actual situation.
Installation using rpm
To install using rpm, first make sure that jdk1.8+ is installed. When using the latest version, if the version of jdk is lower than 1.8, there should be no problem using Jenkins. However, there might be issues when using certain plugins in the future.
Configure jdk
Download jdk1.8 from the jdk official website
$ tar xf jdk-8u231-linux-x64.tar.gz -C /usr/local/
# Add the following content to /etc/profile
export JAVA_HOME=/usr/local/jdk1.8.0_231
export JRE_HOME=${JAVA_HOME}/jre
export CLASSPATH=.:${JAVA_HOME}/lib:${JRE_HOME}/lib
export PATH=${JAVA_HOME}/bin:$PATH
$ source /etc/profile
$ java -version
java version "1.8.0_231"
Java(TM) SE Runtime Environment (build 1.8.0_231-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.231-b11, mixed mode)
After configuring jdk, install Jenkins.
# Download the latest jenkins rpm package from the official website
$ wget https://pkg.jenkins.io/redhat-stable/jenkins-2.204.2-1.1.noarch.rpm
# Install after downloading
$ yum localinstall jenkins-2.204.2-1.1.noarch.rpm
# Start
$ systemctl start jenkins
Start using docker
$ docker run -u root -it -d --name jenkins -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home jenkins/jenkins
You can get the image by searching for keywords on docker hub.
The image will be pulled for the first run.
$ docker run -u root -it -d --name jenkins -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home jenkins/jenkins
Unable to find image 'jenkins/jenkins:latest' locally
latest: Pulling from jenkins/jenkins
3192219afd04: Pull complete
17c160265e75: Pull complete
cc4fe40d0e61: Pull complete
9d647f502a07: Pull complete
d108b8c498aa: Pull complete
1bfe918b8aa5: Pull complete
dafa1a7c0751: Pull complete
78d3391dc013: Pull complete
c1c87cf7f0bf: Pull complete
4bfacf44cce2: Pull complete
9eaefa421a64: Pull complete
043144b011c9: Pull complete
3d9c8a4a5cb8: Pull complete
05fca0659bbd: Pull complete
14241c82960f: Pull complete
41a13492424a: Pull complete
d7aa64814e63: Pull complete
19049899ad6a: Pull complete
3b23f8338127: Pull complete
Digest: sha256:676448a326f96a991d2d32ffbe52f239c0d2c40de3538af2ae6f18d88bf3cb56
Status: Downloaded newer image for jenkins/jenkins:latest
11f86c1472fc4d89e1af5c9340f68e8318b6b7322d46abe30bff23f092a62fe5
# Check the running container
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
11f86c1472fc jenkins/jenkins "/sbin/tini -- /usr/…" 6 minutes ago Up 6 minutes 0.0.0.0:8080->8080/tcp, 0.0.0.0:50000->50000/tcp jenkins
The container maps port 8080 and port 50000 when started, where:
Port 8080 is used for web access.
Port 50000 is the port used by Jenkins agents (slaves) based on JNLP to communicate with the Jenkins master via TCP.
-v jenkins-data:/var/jenkins_home is the mounted volume that mounts the /var/jenkins_home directory in the container to the jenkins-data volume. If this volume does not exist, it will be automatically created when the container is started. You can also manually create it using the command docker volume create jenkins-data, or map it to a specified directory on the host.
After the container starts successfully, access the IP:8080 to view the Jenkins interface as shown below:
It will prompt you to retrieve the administrator secret from the path /var/jenkins_home/secrets/initialAdminPassword (the path may vary depending on whether you installed Jenkins using a war package or rpm). If you installed using the rpm or war package method, simply use the cat command on the server where Jenkins is installed. If you installed using the Docker method, you can use the container ID or container name obtained above to execute the docker command:
$ docker exec -it jenkins cat /var/jenkins_home/secrets/initialAdminPassword
1dc17f65d83c4c56b13cbae230b5e7c6
After obtaining the password, enter it successfully:
Select the desired plugins to install (such as Gradle, Maven, Ant, etc.). This step can also be skipped and the plugins can be installed later as needed. Due to network reasons, the installation may take a while, so please be patient (or refer to “Modify Plugin Update Source” below). Then set the administrator username and password and log in. The following is the Jenkins interface after the installation is complete:
At this point, Jenkins is installed.
Jenkins Basic Configuration #
System Management #
After installing Jenkins, let’s take a look at the Manage Jenkins panel. The Manage Jenkins panel is the entry point for managing, configuring, and maintaining Jenkins. It contains multiple menu items, including the following by default:
Configure System: This menu is used to set the global configuration of Jenkins and various tool plugins, including the working directory of Jenkins, the number of concurrent builds, JDK environment variables, etc.
Configure Global Security: This is the entry point for global security configuration in Jenkins, where you can configure user permissions, API tokens, agent proxies, etc.
Configure Credentials: This menu item is used to create various types of credentials for authenticating systems or services, such as authentication for logging into servers or source code repositories.
Global Tool Configuration: This menu item is used to configure global tools used in Jenkins projects, such as configuring JDK, code compilation tools (Maven/Ant/Gradle), Git configuration for code checkout, etc.
Manage Plugins: This is the entry point for managing Jenkins plugins. You can add, delete, and update plugins. Jenkins relies heavily on plugins to provide powerful features and extensions, so this menu is frequently used.
System Information: This menu displays various system properties of Jenkins, including the configuration of the Jenkins system, Jenkins environment variables, and installed plugins.
System Log: This menu is used to display the system log of Jenkins.
Jenkins CLI: This menu provides instructions on how to use jenkins-cli.jar to operate Jenkins from the command line. It provides a large number of commands and usage instructions for operating Jenkins from the command line. For example, to restart Jenkins, you can use the following command:
java -jar jenkins-cli.jar -s ${jenkins_url} restart
Manage Nodes: This menu is used to manage Jenkins node information, such as adding or removing Jenkins slave nodes, modifying the configuration of master or slave nodes, etc. This will be explained in detail in a later section.
Manage Users: This menu is used to manage system user information in Jenkins, including operations such as adding, deleting, modifying, and searching user information.
The above menus are some commonly used configuration menus in Jenkins. When using Jenkins, you will more or less come into contact with these menus, and detailed configuration instructions for a specific menu will be provided in future studies. I won’t go into much detail here, but if you can’t wait, you can try it out yourself.
Configuration File #
After understanding the panel configuration of Jenkins, let’s take a look at the Jenkins configuration file. After installing Jenkins, the default port is 8080. To access the Jenkins panel, using the IP address and port, click Manage Jenkins -> Configure System to enter the system configuration page, where you can see the default Jenkins configuration, as shown in the following image:
From this image, you can see that the main directory of Jenkins is /var/lib/jenkins. This directory is the actual working directory of Jenkins, where the configuration modifications of Jenkins and the files for storing Jenkins project configurations are placed. It is not the directory where the Jenkins program is executed. From the image above, we can see that this directory cannot be modified in the Jenkins UI interface. How can we modify the working directory path of Jenkins or other configurations such as the startup port and JVM memory? This section briefly explains how to modify these configurations.
For Jenkins services started using Tomcat, you can directly modify the port and JVM memory settings of Tomcat. The modification of the working directory is similar to that of the Jenkins service installed using RPM (it is recommended to keep the default settings). For Jenkins services started using container images, you can refer to the Dockerfile of the Jenkins image in the Docker Hub repository.
So, I won’t go into detail about the configuration files of Jenkins services started using Tomcat or containerization. I will mainly explain the management of the configuration files of Jenkins installed using RPM.
I installed the Jenkins service using the RPM method, and the default start command is systemctl start jenkins (using CentOS 7 as an example). However, I couldn’t find any service files related to Jenkins in the directory where the system default startup files are stored. How can I proceed in this case? By using the systemctl status jenkins command, we can obtain the startup script file for Jenkins, as shown in the example below:
Now that we have found the startup file, let’s take a look at its contents.
$ cat /etc/rc.d/init.d/jenkins |grep -v "^#\|^$"|grep "^JENKINS\|^PARAMS"
JENKINS_WAR="/usr/lib/jenkins/jenkins.war"
JENKINS_CONFIG=/etc/sysconfig/jenkins
JENKINS_PID_FILE="/var/run/jenkins.pid"
JENKINS_LOCKFILE="/var/lock/subsys/jenkins"
PARAMS="--logfile=/var/log/jenkins/jenkins.log --webroot=/var/cache/jenkins/war --daemon"
Explanation
- Here, I filtered out the required content using grep. If you want to see the entire content, you can remove the filtering conditions.
Next, let’s use the ps command to check Jenkins process information.
$ ps -ef|grep jenkins
root 15655 1 2 Apr15 ? 00:31:11 /usr/local/jdk1.8.0_231/bin/java -Djava.awt.headless=true -DJENKINS_HOME=/var/lib/jenkins -jar /usr/lib/jenkins/jenkins.war --logfile=/var/log/jenkins/jenkins.log --webroot=/var/cache/jenkins/war --httpPort=8080 --debug=5 --handlerCountMax=100 --handlerCountMaxIdle=20
From the above information, we can see that the main configuration file for the Jenkins service is /etc/sysconfig/jenkins. It uses a custom java at /usr/local/jdk1.8.0_231/bin/java and is started using a war file. The log file is stored in the /var/log/jenkins/jenkins.log file, and the program files required for running the Jenkins service are placed in the /var/cache/jenkins/war directory. Of course, these configuration paths can be modified.
After understanding the basic configuration information, let’s take a look at the main configuration file for Jenkins.
$ cat /etc/sysconfig/jenkins|grep -v "^#\|^$"
JENKINS_HOME="/var/lib/jenkins"
JENKINS_JAVA_CMD=""
JENKINS_USER="root"
JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true"
JENKINS_PORT="8080"
JENKINS_LISTEN_ADDRESS=""
JENKINS_HTTPS_PORT=""
JENKINS_HTTPS_KEYSTORE=""
JENKINS_HTTPS_KEYSTORE_PASSWORD=""
JENKINS_HTTPS_LISTEN_ADDRESS=""
JENKINS_HTTP2_PORT=""
JENKINS_HTTP2_LISTEN_ADDRESS=""
JENKINS_DEBUG_LEVEL="5"
JENKINS_ENABLE_ACCESS_LOG="no"
JENKINS_HANDLER_MAX="100"
JENKINS_HANDLER_IDLE="20"
JENKINS_EXTRA_LIB_FOLDER=""
JENKINS_ARGS=""
Here, you can see the detailed configuration of Jenkins, including the main working directory of Jenkins, the Jenkins port, the user running Jenkins (default is jenkins), and the java options when Jenkins starts. If you need to modify Jenkins’ JVM parameters, just put the configuration in the JENKINS_JAVA_OPTIONS parameter, separated by spaces. After modifying the configuration file, don’t forget to restart the Jenkins service.
Jenkins Localization #
After installing Jenkins, the default language is usually English. Some users may not be comfortable with the English version of Jenkins and may want to localize it to Chinese. Localization is relatively simple and can be done by following the configuration steps below.
Go to “Manage Jenkins” -> “Manage Plugins” and search for the Locale plugin in the available plugins. Click on Install to install the plugin.
After installation, go to the “Config System” menu and find the Locale option configuration. Set “Default Language” to zh_CN and check the box for “Ignore browser preference and force this language to all users”.
Refer to the image below:
After configuring, restart Jenkins and you will see that the English menu has been translated to Chinese on the login page.
The method for localizing Jenkins may vary depending on the installation method or version. For most versions, the above method should work. However, if after installing the plugin and restarting Jenkins, the interface is still in English, you may need to install the Localization: Chinese (Simplified) plugin and restart Jenkins again. If you find that the interface is partially in Chinese and partially in English after localization, it may be related to the version or installation method of Jenkins.
Modifying the Plugin Update Source #
Jenkins relies on plugins for its powerful functionality and extensions. When installing Jenkins, or after installing it, you need to install many essential plugins. However, using the default Jenkins plugin source provided by the official website can result in either slow download speeds or installation failures, greatly reducing both work efficiency and learning efficiency. To solve this problem, you need to modify the mirror source that Jenkins uses to download plugins.
Navigate to the “Manage Jenkins” -> “Manage Plugins” -> “Advanced” page. Most online methods suggest modifying the value of the URL input box under “Update Site” on this page. Set it to either the Tsinghua source or the Domestic source in the Jenkins plugin center. The screenshot below shows the process:
After making this modification, the download speed of the mirror may still be slow. This is because Jenkins retrieves plugin versions and downloads the plugins by parsing the update-center.json file. However, Jenkins uses a private key to sign the update-center.json file, so only the update-center.json file that has passed the public key verification will be used. Therefore, you also need to replace the key and certificate files used by Jenkins.
Replacing the Certificate Files
Download the mirror-adapter.crt file from https://github.com/jenkins-zh/mirror-adapter/rootCA and place it in the /var/cache/jenkins/war/WEB-INF/update-center-rootCAs directory.
To simplify this configuration process, the Jenkins Chinese Community has solved the key and address issues. You can follow the steps below:
In the bottom right corner of the Jenkins panel, click on Jenkins中文社区 (Jenkins Chinese Community). On the redirected page, there will be a “Update Center Mirror Settings” section, as shown below:
Note:
First, click on “Use”, and then click on “Set Update Center URL”. On the redirected page, enter the address provided above.
If you don’t see the Jenkins中文社区 (Jenkins Chinese Community) button, it may be because you haven’t installed the Chinese language pack.
Password Modification #
When using Jenkins, you may often encounter situations where you forget the login password for the Jenkins administrator. If you forget the password, what should you do? You can modify the Jenkins configuration file ${JENKINS_HOME}/config.xml. Find:
<useSecurity>true</useSecurity>
Change true to false, then restart Jenkins.
After Jenkins restarts, you can access Jenkins without verification and directly go to the Jenkins dashboard interface. Then click “Manage Jenkins” -> “Configure Global Security”, check “Enable security”, in the “Access Control” section, under the “Security Realm” property, select “Jenkins’ own user database”, and under the “Authorization strategy” property, select “Logged-in users can do anything”. As shown below:
After saving, go to the “Manage Users” interface to reset the password for the administrator user.
Backup and Restore #
Another essential configuration for Jenkins is backup. All data in Jenkins is stored as files in the ${JENKINS_HOME} directory. Therefore, whether it is for migration or backup purposes, all you need to do is to package the ${JENKINS_HOME} directory, copy it, and then extract the packaged files into the new ${JENKINS_HOME} directory. There are many ways to back up Jenkins, and this article will briefly introduce a commonly used method using the ThinBackup plugin.
First, find the ThinBackup plugin in the plugin management page, and install it (if you do not know how to install, please refer to the second article). After installation, a ThinBackup menu item will appear in the Manage Jenkins interface. Clicking on it will take you to the settings page for backup. The settings are as follows:
Explanation:
Backup directory: The directory for storing backup files. If the specified directory does not exist, it will be automatically created before performing the backup.
Backup schedule for full backups: The schedule for performing full backups, similar to crontab in Linux. The ‘H’ above represents a hash, which allows tasks that are scheduled periodically to generate an even load on the system. It is recommended to use the symbol H (for “hash”) as much as possible. For example, if multiple jobs are set to use 0 0 * * *, it will cause a significant increase in load. In comparison, using H H * will still execute each job once a day, but not simultaneously, making better use of limited resources.
Backup schedule for differential backups: The schedule for performing differential backups, same as above.
Max number of backup sets: The maximum number of backups.
Files excluded from backup (regular expression): Regular expression for files that do not need to be backed up.
Wait until Jenkins/Hudson is idle to perform a backup: How long to wait for Jenkins to be idle before performing a backup.
Backup build results: If enabled, build results will also be backed up. Generally, it is not recommended to check this option.
Backup ‘userContent’ folder: Back up files under the ${jenkins_home}/userContent directory.
Backup next build number file: Backup the build ID file of Jenkins.
Backup plugins archives: Backup plugins.
Clean up differential backups: Clear all differential backups after completing the backup.
Move old backups to ZIP files: If this option is selected, whenever a new full backup is performed, all old backup sets will be moved to ZIP files. Each ZIP file will contain a backup set, which includes a full backup and any differential backups that refer to that backup file. The file name will indicate the time range that the backup covers (i.e., the timestamp of the full backup and the timestamp of the latest differential backup).
Customize the backup strategy according to your actual situation.
After saving, go back to the ThinBackup interface. In addition to automatic backups, you can also perform manual backups by clicking the Backup Now button, which will initiate an immediate backup. The button is as follows:
After the backup is complete, a directory named with FULL- at the beginning and the current time (in minutes) at the end will be generated in the backup directory set above. This directory contains all the default Jenkins configurations.
When using a backup file for restore, click the restore button, and the redirected page will display the backup time of the backup file. Clicking on Restore will initiate the restore process.
In general, using this plugin for backup is relatively simple. There is no need to elaborate further here. If you are interested, you can try it out yourself.