Recent Blog Posts

This article describes our observations during Windows testing of the Jenkins 2.249.1 release candidate. Upgrade testing Jenkins 2.249.1 is a new long term support release with user interface improvements and changes in Windows support. It is the first long term support release to drop support for Microsoft.NET framework 2.0. The end of support for Microsoft.NET framework 2.0 was announced in the Windows Support Updates blog post. The Windows support upgrade guidelines describe major things to consider when upgrading Jenkins controllers and agents on Windows. As part of our preparation for the release, we tested several configurations. This article describes our experiences with those configurations. Upgrade approaches We tested controller and agent upgrades from Jenkins 2.235.x to 2.249.1-rc on Windows. The tests included: 32 bit Windows MSI 64 bit Windows MSI WAR (file) on Windows Upgrade process Our upgrade process included: Install a previous version of Jenkins controller on Windows Install a previous version of Jenkins agent on Windows and configure it as a service Upgrade Jenkins controller from "Manage Jenkins" Restart the Jenkins Windows service for the controller Upgrade the Jenkins agent on Windows with the latest agent.jar Restart the Jenkins Windows service for the agent Testing results We successfully tested Restarting Windows service for controller ( JENKINS-63198) Restarting Windows service for agents ( JENKINS-63223) We confirmed that we can continue our Level 1 support policy for Jenkins 2.249.1. 32 bit Windows MSI Prior to Jenkins 2.235.3, the Jenkins LTS Windows installer was provided as a 32 bit MSI and included a bundled Java 8 runtime environment. The Jenkins agent can be downloaded and run through Java web start using the bundled Java 8 runtime environment. The agent can also be configured to run as a service using the bundled Java 8 runtime environment. Jenkins controller Jenkins 2.235.1 installs JRE 8u144 for 32 bit Windows. The installer configures the Jenkins controller to run as the SYSTEM user. Refer to the Windows Installer Updates blog post for details of the controller installation process with the 32 bit MSI. Jenkins agent Jenkins agents on Windows are often configured to "Launch agent by connecting it to the master". The Jenkins agent configuration correctly warns that the controller must open the TCP port for inbound agents in the "Configure Global Security" page. It is easiest to allow Jenkins to choose the port (a "Random" port). Jenkins selects a random available port number and shares that port number with agents during their initial connection to the Jenkins http port. Configure the agent Once the Jenkins TCP port is open for inbound agents, a new agent is configured from the Jenkins "Nodes" menu This creates an "inbound Jenkins agent" that uses the Jenkins agent.jar to initiate the connection to the Jenkins controller. Download the agent The agent starts the first time by clicking the "Launch" button on the agent configuration page (only available with Java 8). That downloads the "slave-agent.jnlp" file from the web browser. Start the agent The downloaded file needs to be opened from a command prompt using the javaws command that is included with the bundled JRE: C:\> "C:\Program Files (x86)\Jenkins\jre\bin\javaws.exe" -wait slave-agent.jnlp The javaws program has been removed from the most recent releases of Java 8 and from Java 11. Refer to [Jenkins agent and icedtea] for a technique that can help users of the most recent releases of Java 8. Java web start (javaws.exe) prompts for permission to run the program with this dialog: Install the agent as a service The agent runs and displays a window on the desktop with a single menu entry, "Install as a service". When the "Install as a service" menu item is clicked, the agent is adjusted to run as a Windows service using the SYSTEM account. Upgrade the controller The Jenkins controller on Windows can be upgraded to Jenkins 2.249.1 from the "Manage Jenkins" page. The upgrade process downloads the new jenkins.war file, saves the current version in case of later downgrade, and offers to restart. Upgrade the agent The Jenkins inbound agent is not upgraded automatically. The agent administrator downloads the most recent agent.jar from their Jenkins controller, stops the running agent, and replaces the installed agent.jar with the downloaded version. The agent service will reconnect to the Jenkins controller after the administrator restarts it. 64 bit Windows MSI Beginning with Jenkins 2.235.3, the Jenkins LTS Windows installer is a 64 bit MSI. It runs Jenkins with the 64 bit JDK (Java 8 or Java 11) selected by the user. Jenkins controller Jenkins 2.235.3 was installed using AdoptOpenJDK Java 8u262 in one test. It was installed using AdoptOpenJDK Java 11.0.8 in another test. In both cases, the installer configured the Jenkins controller to run with the Windows service account we had previously configured. Refer to the Windows Installer Updates blog post for details of the controller installation process with the 64 bit MSI. Jenkins agent Jenkins agents on Windows are often configured to "Launch agent by connecting it to the master". The Jenkins agent configuration correctly warns that the controller must open the TCP port for inbound agents in the "Configure Global Security" page. It is easiest to allow Jenkins to choose the port (a "Random" port). Jenkins selects a random available port number and shares that port number with agents during their initial connection to the Jenkins http port. Configure the agent Once the Jenkins TCP port is open for inbound agents, a new agent is configured from the Jenkins "Nodes" menu This creates an "inbound Jenkins agent" that uses the Jenkins agent.jar to initiate the connection to the Jenkins controller. Once the Jenkins TCP port is open for inbound agents, a new agent is configured from the Jenkins "Nodes" menu This creates an "inbound Jenkins agent" that uses the Jenkins agent.jar to initiate the connection to the Jenkins controller. Once the Jenkins TCP port is open for inbound agents, a new agent is configured from the Jenkins "Nodes" menu This creates an "inbound Jenkins agent" that uses the Jenkins agent.jar to initiate the connection to the Jenkins controller. Download the agent The agent was started the first time by clicking the "Launch" button on the agent configuration page (only available with Java 8). That downloads the "slave-agent.jnlp" file from the web browser. Start the agent with IcedTea-Web Recent versions of Java 8 and all versions of Java 11 have removed the javaws command. Jenkins agents for Java 8 can still be started with the javaws command, but it needs to be downloaded separately from the JVM. We open "slave-agent.jnlp" from a command prompt using the javaws command that is available from AdoptOpenJDK IcedTea : C:\> C:\icedtea-web-1.8.3.win.bin\icedtea-web-image\bin\javaws.exe -wait slave-agent.jnlp Java web start (javaws.exe) prompts for permission to run the program with this dialog: Install the agent as a service The agent runs and displays a window on the desktop with a single menu entry, "Install as a service". When the "Install as a service" menu item is clicked, the agent is installed and configured to run as a Windows service using the SYSTEM account. Upgrading the controller The Jenkins controller on Windows was upgraded to Jenkins 2.249.1 from the "Manage Jenkins" page. The upgrade process downloads the new jenkins.war file, saves the current version in case of later downgrade, and offers to restart. Upgrading the agent The Jenkins inbound agent is not upgraded automatically or from a Jenkins user interface. The agent administrator downloads the most recent agent.jar from their Jenkins controller and replaces the installed agent.jar with the downloaded version. WAR (file) on Windows Jenkins allows users to run the Jenkins web archive (WAR) file from a command line and then install it as a service from within Jenkins. This installation technique uses the Jenkins WAR file but does not use a Windows MSI package. The Jenkins WAR file includes the necessary components to install and configure Jenkins as a service. Install controller as a service When the Jenkins war file is started from a Windows command prompt, "Manage Jenkins" includes "Install as a service". An administrator selects that entry and Jenkins will configure itself to run as a service/ The installer configures the Jenkins controller to run as the SYSTEM user. Jenkins agent Jenkins agents on Windows are often configured to "Launch agent by connecting it to the master". The Jenkins agent configuration correctly warns that the controller must open the TCP port for inbound agents in the "Configure Global Security" page. It is easiest to allow Jenkins to choose the port (a "Random" port). Jenkins selects a random available port number and shares that port number with agents during their initial connection to the Jenkins http port. Configure the agent After opening the Jenkins TCP port for inbound agents, we configured a new agent from the "Nodes" menu This created an "inbound Jenkins agent" that uses the Jenkins agent.jar to initiate the connection to the Jenkins controller. Download the agent The agent was started the first time by clicking the "Launch" button on the agent configuration page (only available with Java 8). That downloads the "slave-agent.jnlp" file from the web browser. Start the agent with IcedTea-Web Recent versions of Java 8 and all versions of Java 11 have removed the javaws command. Jenkins agents for Java 8 can still be started with the javaws command, but it needs to be downloaded separately from the JVM. Open "slave-agent.jnlp" from a command prompt using the javaws command that is available from AdoptOpenJDK IcedTea-Web : C:\> C:\icedtea-web-1.8.3.win.bin\icedtea-web-image\bin\javaws.exe -wait slave-agent.jnlp Java web start (javaws.exe) prompts for permission to run the program with this dialog: Install the agent as a service The agent runs and displays a window on the desktop with a single menu entry, "Install as a service". When the "Install as a service" menu item is clicked, the agent is installed and configured to run as a Windows service using the SYSTEM account. Conclusion Jenkins controller installation is best done with the new 64 bit MSI package. Previous controller installations can be upgraded to the most recent Jenkins release from within Jenkins. Jenkins inbound agent installation is more complicated now that the javaws.exe program is not included in the JDK. The AdoptOpenJDK IcedTea-Web project allows administrators to install and configure Jenkins inbound agents with most of the ease that was available in prior Java releases.

This article describes the transition from the old Jenkins Windows installer 2.235.2 (32 bit) to the new Jenkins Windows installer 2.235.3 (64 bit) Let’s take a look how Jenkins installation on Windows happened before release of this upgrade. Step 1 It’s evident that branding information is not present here. Step 2 Jenkins would be installed into the 32 bit programs directory along with a 32 bit Java 8 runtime environment. Step 3 There was no option to select the user that would run the Jenkins service or the network port that would be used. Issues The previous installer had issues that needed to be resolved: Only supported 32-bit installations Bundled an outdated Java 8 runtime environment No support for Java 11 No port selection during installation No choice of account for the Jenkins service The Program Files (x86) directory was used for the Jenkins home directory Road Forward The new Jenkins Windows Installer resolves those issues Supports 64 bit installations and drops 32 bit support Supports 64 bit Java 8 and 64 bit Java 11 Port selection and validation from the installer Service account selection and validation from the installer Program is installed in Program Files with Jenkins home directory in %AppData% of the selected service account The JENKINS_HOME directory is placed in the LocalAppData directory for the user that the service will run as, this aligns with modern Windows file system layouts The installer has been updated with branding to make it look nicer and provide a better user experience Screenshots You may see below the sequence of screenshots for the new installer: Step 1 We can see now the Jenkins logo as a prominent part of the installer UI. Step 2 Jenkins installs by default in the 64 bit programs folder rather than in the 32 bit folder. Now the Jenkins logo and name are in the header during entire process of installation. Step 3 Now the installer allows both specifying and testing the credentials by validating that the account has LogonAsService rights. Step 4 Now the installer also allows specifying the port that Jenkins should run on and will not continue until a valid port is entered and tested. Step 5 Now instead of bundling a JRE, the installer searches for a compatible JRE on the system (in the current search no JRE was installed). In case you would like to use a different JRE from the one found by the installer, you can browse and specify it. Only Java 8 and Java 11 runtimes are supported. In case the selected JRE is found to be version 11 the installer will automatically add the necessary arguments and additional jar files for running under Java 11. Step 6 All of the items that users can enter in the installer should be overridable on the command line for automated deployment as well. The full list of properties that can be overridden will be available soon. Next Steps Windows users have alternatives for their existing Jenkins installations: Upgrade from inside Jenkins The "Manage Jenkins" section of the running Jenkins will continue to include an "Upgrade" button for Windows users. You may continue to use that "Upgrade" button to update the Jenkins installation on your Windows computer. Upgrade from inside Jenkins will continue to use the current Java version. Upgrade from inside Jenkins will continue to use the current installation location. Upgrade with the new Jenkins MSI installer If you run the new Jenkins MSI installer on your Jenkins that was installed with the old Jenkins MSI installer, it will prompt for a new port and a service account. Stop and disable the existing Jenkins service from the Windows Service Manager Run the new installer to create the new installation with desired settings Stop the newly installed Jenkins service Copy existing Jenkins configuration files to the new Jenkins home directory Start the newly installed Jenkins service After the new Jenkins MSI installer has run, the "Manage Jenkins" section of the running Jenkins will continue to include an "Upgrade" button for Windows users. You may continue to use that "Upgrade" button to update the Jenkins installation on your Windows computer.

The Windows Installer for Jenkins has been around for many years as a way for users to install a Jenkins controller on Windows as a service. Since it’s initial development, it has not received a lot of updates or features, but that is about to change. First, let’s take a look at the current installer experience. Step 1 This is the default look and feel for a Windows Installer using the WiX Toolset, not very pretty and doesn’t give much branding information as to what the installer is for. Step 2 Again, not much branding information. Step 3 The installer in general does not give many options for installing Jenkins, other than selecting the installation location. Issues The current installer has a few issues that the Platform SIG wanted to fix in a new install experience for users. The installer only supports 32-bit installations. The user could not select ports or user accounts to run the service on. The installer bundled a 32-bit version of the Java runtime instead of using a pre-existing JRE The installer did not support the experimental support in Jenkins for Java 11 The JENKINS_HOME directory was not placed in a good spot for modern Windows There is no branding in the installer. Road Forward With the experimental Jenkins Windows Installer, most of these issues have been resolved! The installer will only support 64-bit systems going forward. This is the vast majority of Windows systems these days, so this will help more users install Jenkins using the installer package. The user is now able to enter user information for the service and select the port that Jenkins will use and verify that the port is available. The installer no longer bundles a JRE, but will search for a compatible JRE on the system. If the user wants to use a different JRE, they can specify during install. The installer has support for running with a Java 11 JRE, including the components listed on the Java 11 Preview Page. the JENKINS_HOME directory is placed in the LocalAppData directory for the user that the service will run as, this aligns with modern Windows file system layouts. The installer has been updated with branding to make it look nicer and provide a better user experience. Screenshots Below are screenshots of the new installer sequence: Step 1 The Jenkins logo is now a prominent part of the UI for the installer. Step 2 The Jenkins logo and name are now in the header during all phases of the installer. Step 3 The installer now allows you to specify the username/password for the account to run as and checks that the account has LogonAsService rights. Step 4 The installer also allows you to specify the port that Jenkins should run on and will not continue until a valid port is entered and tested. Step 5 Instead of bundling a JRE, the installer now searches for a compatible JRE on the system (JRE 8 is the current search). If you want to use a different JRE on the system than the one found by the installer, you can browse and specify it. Only JRE 8 and JRE 11 runtimes are supported. The installer will automatically add the necessary arguments and additional jar files for running under Java 11 if the selected JRE is found to be version 11. Step 6 All of the items that users can enter in the installer should be overridable on the command line for automated deployment as well. The full list of properties that can be overridden will be available soon. Next Steps The new installer is under review by the members of the Platform SIG, but we need people to test the installer and give feedback. If you are interested in testing the new installer, please join the Platform SIG gitter room for more information. There are still some things that are being researched and implemented in the new installer (e.g., keeping port and other selections when doing an upgrade), but it is getting close to release. In addition to updates to the MSI based Windows installer, the Platform SIG is working on taking over the Chocolatey Jenkins package and releasing a version for each update.