3.13. What’s in the Jenkins Home Directory

The Jenkins home directory contains all the details of your Jenkins server configuration, details that you configure in the Manage Jenkins screen. These configuration details are stored in the form of a set of XML files. Much of the core configuration, for example, is stored in the config.xml file. Other tools-specific configuration is stored in other appropriately-named XML files: the details of your Maven installations, for example, are stored in a file called hudson.tasks.Maven.xml . You rarely need to modify these files by hand, though occasionally it can come in handy.

The Jenkins home directory also contains a number of subdirectories (see Figure 3.7, “The Jenkins home directory” ). Not all of the files and directories will be present after a fresh installation, as some are created when required by Jenkins. And if you look at an existing Jenkins installation, you will see additional XML files relating to Jenkins configuration and plugins.

The main directories are described in more detail in Table 3.1, “The Jenkins home directory structure” .

Table 3.1. The Jenkins home directory structure

Directory Description
.jenkins The default Jenkins home directory (may be .hudson in older installations).
fingerprints This directory is used by Jenkins to keep track of artifact fingerprints. We look at how to track artifacts later on in the book.
jobs This directory contains configuration details about the build jobs that Jenkins manages, as well as the artifacts and data resulting from these builds. We look at this directory in detail below.
plugins This directory contains any plugins that you have installed. Plugins allow you to extend Jenkins by adding extra feature. Note that, with the exception of the Jenkins core plugins (subversion, cvs, ssh-slaves, maven, and scid-ad), plugins are not stored with the jenkins executable, or in the expanded web application directory. This means that you can update your Jenkins executable and not have to reinstall all your plugins.
updates This is an internal directory used by Jenkins to store information about available plugin updates.
userContent You can use this directory to place your own custom content onto your Jenkins server. You can access files in this directory at http://myserver/hudson/userContent (if you are running Jenkins on an application server) or http://myserver/userContent (if you are running in stand-alone mode).
users If you are using the native Jenkins user database, user accounts will be stored in this directory.
war This directory contains the expanded web application. When you start Jenkins as a stand-alone application, it will extract the web application into this directory.

The Jenkins home directory

Figure 3.7. The Jenkins home directory

The jobs directory is a crucial part of the Jenkins directory structure, and deserves a bit more attention. You can see an example of a real Jenkins jobs directory in Figure 3.8, “The Jenkins jobs directory” .

The Jenkins jobs directory

Figure 3.8. The Jenkins jobs directory

This directory contains a subdirectory for each Jenkins build job being managed by this instance of Jenkins. Each job directory in turn contains two subdirectories: builds and workspace , along with some other files. In particular, it contains the build job config.xml file, which contains, as you might expect, the configuration details for this build job. There are also some other files used internally by Jenkins, that you usually wouldn’t touch, such as the nextBuildNumber file (which contains the number that will be assigned to the next build in this build job), as well as symbolic links to the most recent successful build and the last stable one. A successful build is one that does not have any compilation errors. A stable build is a successful build that has passed whatever quality criteria you may have configured, such as unit tests, code coverage and so forth.

Both the build and the workspace directories are important. The workspace directory is where Jenkins builds your project: it contains the source code Jenkins checks out, plus any files generated by the build itself. This workspace is reused for each successive build—there is only ever one workspace directory per project, and the disk space it requires tends to be relatively stable.

The builds directory contains a history of the builds executed for this job. You rarely need to intervene directly in these directories, but it can be useful to know what they contain. You can see a real example of the builds directory in Figure 3.9, “The builds directory” , where three builds have been performed. Jenkins stores build history and artifacts for each build it performs in a directory labeled with a timestamp (“2010-03-12_20-42-05” and so forth in Figure 3.9, “The builds directory” ). It also contains symbolic links with the actual build numbers that point to the build history directories.

The builds directory

Figure 3.9. The builds directory

Each build directory contains information such as the build result log file, the Subversion revision number used for this build (if you are using Subversion), the changes that triggered this build, and any other data or metrics that you have asked Jenkins to keep track of. For example, if your build job keeps track of unit test results or test coverage metrics, this data will be stored here for each build. The build directory also contains any artifacts you are storing—binary artifacts, but also other generated files such as javadoc or code coverage metrics. Some types of build jobs, such as the Jenkins Maven build jobs, will also archive binary artifacts by default.

The size of the build directory will naturally grow over time, as the build history cumulates. You will probably want to take this into account when designing your build server directory structure, especially if your build server is running in a Unix-style environment with multiple disk partitions. A lot of this data takes the form of text or XML files, which does not consume a large amount of extra space for each build. However, if your build archives some of your build artifacts, such as JAR or WAR files, they too will be stored here. The size of these artifacts should be factored into your disk space requirements. We will see later on how to limit the number of builds stored for a particular build job if space is an issue. Limiting the number of build jobs that Jenkins stores is always a trade-off between disk space and keeping useful build statistics, as Jenkins does rely on this build history for its powerful reporting features.

Jenkins uses the files in this directory extensively to display build history and metrics data, so you should be particularly careful not to delete any of the build history directories without knowing exactly what you are doing.