Migrating from Jenkins LTS to CloudBees Jenkins Distribution
CloudBees no longer supports CloudBees Jenkins Distribution as of February 24, 2021. Please refer to the following step-by-step documentation for Migrating from CloudBees Jenkins Distribution to Jenkins LTS. The increased alignment between CloudBees Jenkins Distribution and Jenkins means users will experience zero impact to Pipeline execution. Existing customers can also contact CloudBees Support to help ensure a smooth transition. Please see About the CloudBees Jenkins Distribution retirement for more information. |
This guide covers migration from Jenkins LTS to CloudBees Jenkins Distribution.
CloudBees Jenkins Distribution, similar to Jenkins, can run as a stand-alone Java process inside a Java servlet container engine (like Jetty) or as a Docker container.
Regardless of the configuration, please ensure that the machine running CloudBees Jenkins Distribution meets the system requirements before continuing.
These instructions assume that the version of your Jenkins instance matches that of a recent LTS. CloudBees Jenkins Distribution is based upon the Jenkins LTS: for example, CloudBees Jenkins Distribution <version> is based on Jenkins <version> (and is therefore considered a relatively straightforward upgrade). |
If your Jenkins version is one of the "weekly" releases, or a Jenkins LTS version older than 2.150.2, please contact CloudBees Support for an Assisted Update.
System Requirements for CloudBees Jenkins Distribution
CloudBees Jenkins Distribution requires at least 512 MB of RAM and 2 GB of disk space, but it is recommended that administrators plan for at least 4 GB of RAM and 50 GB+ of free disk space to allow for room to grow with workloads on CloudBees Jenkins Distribution.
CloudBees Jenkins Distribution is available as a standalone WAR file, which can run in practically any Java runtime environment. CloudBees Jenkins Distribution is also available via native packages distributed for the following platforms:
-
Debian / Ubuntu
-
Red Hat / CentOS
-
openSUSE / SUSE Linux
-
Windows
There are no universally applicable operating system-level requirements, but depending on the workload placed on the instance, your instance may require changes to certain tunables such as heap size or open file descriptor limits.
The native packages for CloudBees Jenkins Distribution include a Java runtime environment. Administrators wishing to run the WAR file on its own, or deploy CloudBees Jenkins Distribution in a Java Servlet Container should bear in mind that CloudBees supports:
-
Oracle JRE 8
-
OpenJDK JRE 8
CloudBees Jenkins Distribution may run on older, non-supported Java runtime environments. Administrators running older versions of Java should expect "best effort" support for any potential technical issues which may arise. Please refer to Supported Platforms for more detailed information.
An important note about users
The user that runs Jenkins is CHANGING to cloudbees-jenkins-distribution .
|
It is very important that:
-
The
cloudbees-jenkins-distribution
user exists on your system. -
The
cloudbees-jenkins-distribution
user has the appropriate privileges to run Jenkins. -
The
cloudbees-jenkins-distribution
user is running in a secure manner to prevent privilege-escalation exploits.
If you have questions about setting up the cloudbees-jenkins-distribution
user, please contact CloudBees Support.
Linux
When upgrading from Jenkins on Linux, this guide assumes that the current
Jenkins instance is using the Jenkins project’s official Linux (rpm
or deb
)
packages, and that the CloudBees Jenkins Distribution instance that is being upgraded also uses Linux packages.
These instructions also assume that the home directory (commonly referred to as
JENKINS_HOME
in configuration scripts and documentation) is
/var/lib/jenkins
.
Red Hat Enterprise Linux / CentOS
To migrate from Jenkins to CloudBees Jenkins Distribution on Red Hat Enterprise Linux or CentOS systems, follow these instructions.
Remove the previously installed jenkins
package
Replace the previously installed jenkins
package with the cloudbees-jenkins-distribution
package:
shell% yum remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
1 | This command removes the previously installed jenkins package from the system. |
2 | This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents. |
Install CloudBees Jenkins Distribution for Red Hat Enterprise Linux / CentOS
Administrators running Red Hat-based distributions, such as Red Hat Enterprise Linux, Fedora, Oracle Linux, and CentOS, first need to set up the RPM repository for CloudBees Jenkins Distribution and import the key.
-
Set up the RPM repository:
sudo wget -O /etc/yum.repos.d/cloudbees-jenkins-distribution.repo https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees-jenkins-distribution.repo
-
Import the CloudBees key:
sudo rpm --import https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees.com.key
If the CloudBees key has already been imported on the machine, the rpm --import
command will fail. This error can be safely ignored. -
Once the repository and key have been set up, CloudBees Jenkins Distribution can be installed with
yum
via:sudo yum install cloudbees-jenkins-distribution
-
Set the
cloudbees-jenkins-distribution
service to automatically start on boot:sudo chkconfig --add cloudbees-jenkins-distribution
Change ownership
Once installation is complete, change the ownership of the previous JENKINS_HOME
to the cloudbees-jenkins-distribution
user:
shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins
Debian/Ubuntu
To migrate from Jenkins to CloudBees Jenkins Distribution on Debian or Ubuntu systems, follow these instructions.
Remove the previously installed jenkins
package
Replace the previously installed jenkins
package with the cloudbees-jenkins-distribution
package:
shell% apt-get remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
1 | This command removes the previously installed jenkins package from the system. |
2 | This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use
the same home directory and its contents. |
Install CloudBees Jenkins Distribution for Debian/Ubuntu
Administrators running Debian-based distributions such as Debian or Ubuntu will need to add an APT repository and key in order to install CloudBees Jenkins Distribution.
-
To use the Debian package repository of CloudBees Jenkins Distribution to automate installation and upgrade, first add the key to your system:
wget -q -O - https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian/cloudbees.com.key | sudo apt-key add -
-
Edit
/etc/apt/sources.list
and add the entry for CloudBees Jenkins Distribution:deb https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian binary/
-
Update your local package index:
sudo apt-get update
-
Install CloudBees Jenkins Distribution:
sudo apt-get install cloudbees-jenkins-distribution
Older versions of Debian and Ubuntu do not provide a Java 8 package and CloudBees Jenkins Distribution may fail to install as a result. Using newer versions of these distributions which provide Java 8 is strongly recommended.
Change ownership
Once installation is complete, change the ownership of the previous JENKINS_HOME
to the cloudbees-jenkins-distribution
user:
shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins
openSUSE / SUSE Linux
To migrate from Jenkins to CloudBees Jenkins Distribution on openSUSE- or SUSE Linux-based systems, follow these instructions:
Remove the previously installed jenkins
package
Replace the previously installed jenkins
package with the cloudbees-jenkins-distribution
package:
shell% zypper remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
1 | This command removes the previously installed jenkins package from the system. |
2 | This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents. |
Install CloudBees Jenkins Distribution for openSUSE / SUSE Linux
Use the zypper
command to install CloudBees Jenkins Distribution on openSUSE-based distributions.
-
First, add the CloudBees RPM repository:
sudo zypper addrepo -f https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/opensuse/ cloudbees-jenkins-distribution
-
Next, run:
sudo zypper install cloudbees-jenkins-distribution
Change ownership
Once installation is complete, change the ownership of the previous JENKINS_HOME
to the cloudbees-jenkins-distribution
user:
shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins
Microsoft Windows
To migrate from Jenkins to CloudBees Jenkins Distribution on Microsoft Windows systems, follow these instructions.
Remove the previously installed jenkins
package and rename folders
Remove the previously installed jenkins
package:
-
Stop the
jenkins
service and delete it. -
Rename the folder where the
jenkins
service was running fromProgram Files (x86)/Jenkins
toProgram Files (x86)/CloudBeesJenkinsDistribution
Folder names may vary depending on where the Jenkins LTS was installed.
Download, install, and run CloudBees Jenkins Distribution for Microsoft Windows
To run CloudBees Jenkins Distribution on Microsoft Windows, use the MSI file from the CloudBees Jenkins Distribution download site.
-
Download the cloudbees-jenkins-distribution.zip file, and the SHA256 checksum file.
-
The checksum file can be used to verify that the
cloudbees-jenkins-distribution.zip
is correct. Compare the contents ofcloudbees-jenkins-distribution.zip.sha256
with the output of the following PowerShell command:$(CertUtil -hashfile D:\Users\USER\Downloads\cloudbees-jenkins-distribution.zip SHA256)[1] -replace " ",""
-
Unpack the archive and execute the CloudBees Jenkins Distribution installer,
cloudbees-jenkins-distribution.msi
.The CloudBees Jenkins Distribution installer for Microsoft Windows requires a 64-bit operating system and a compatible .NET framework (2.0, 3.5.1, 4.0) in order to be installed as a service. Most Microsoft Windows versions install a compatible framework by default.
After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default.
Docker
To migrate from Jenkins to CloudBees Jenkins Distribution on Docker-based systems, follow these instructions:
Stop and delete the previously installed container service
Stop and delete the previously installed container service and update it with an appropriate Docker image.
shell% docker stop <Jenkins container name> && docker rm <Jenkins container name> (1)
shell% docker pull cloudbees/cloudbees-jenkins-distribution (2)
shell% docker run --name <Jenkins container name> -p 18080:8080 -v /tmp/docker/:/var/jenkins_home [IMAGE_ID] (3)
1 | This command stops and deletes the previous container. |
2 | This command pulls a new Docker image from CloudBees. |
3 | This command launches a container from the new image with the same name (<Jenkins container name> ) and same JENKINS_HOME volume. |
After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default.
Stand-alone WAR file
While it is strongly recommended that administrators rely on the native
packages above, CloudBees Jenkins Distribution can be run as a stand-alone WAR file with an existing
JENKINS_HOME
.
Install and run CloudBees Jenkins Distribution for stand-alone WAR files
-
Download the WAR file for CloudBees Jenkins Distribution; for your operating system and copy it to where you wish to run CloudBees Jenkins Distribution.
-
Copy the file to the directory where you wish to run CloudBees Jenkins Distribution.
-
Open a terminal and run the command:
java -jar cloudbees-jenkins-distribution.war
-
The process output generates a password offset by three rows of asterisks above and below the text. Copy the password. The password is also saved in a directory like
/users/<username>.jenkins/secrets/initialAdminPassword
, whereusername
is replaced with your username. The exact path may vary depending upon your operating system.************************************************************* ************************************************************* ************************************************************* Jenkins initial setup is required. An admin user has been created and a password generated. Please use the following password to proceed to installation: d661ea28c6b94406ad627601b6f4aa877 This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword ************************************************************* ************************************************************* *************************************************************
-
The terminal portion is complete when the output reads:
INFO: Obtained the updated data file for hudson.tools.JDKInstaller Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get INFO: Beekeeper is parsing UpdateSite cloudbees-jenkins-distribution-offline Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get INFO: Beekeeper is parsing UpdateSite cap-cloudbees-jenkins-distribution Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run INFO: Started telemetry collection Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run INFO: Finished telemetry collection. 1 ms
To complete the migration, set the JENKINS_HOME
environment variable to the existing Jenkins home directory. For example:
shell% JENKINS_HOME=/var/lib/jenkins java -jar cloudbees-jenkins-distribution.war
Kubernetes deployment
Migrating from a Jenkins LTS instance deployed on a Kubernetes cluster to CloudBees Jenkins Distribution consists of three steps:
-
Configuring the Persistent Volume so it can be used by the new CloudBees Jenkins Distribution instance.
-
Changing the Jenkins home location.
-
Upgrading the deployment.
Prerequisites
These migration instructions assume that any cluster management tools such as kubectl
or helm
have been properly installed and configured.
The Kubernetes cluster must be configured with either a Persistent Volume (PV) or Persistent Volume Claim (PVC). This prevents data loss when the Jenkins pod is terminated, and permits you to change the Jenkins home location. For detailed instructions and explanation, see the Kubernetes documentation for Persistent Volumes. |
Configuring the Persistent Volume
Configuring the Persistent Volume requires three actions:
Identifying the PVC and PC
PVCs and PVs are identified by name. To retrieve the name:
-
Identify the PVC
shell% kubectl get pvc NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE my-ci-jenkins Bound pvc-66bb97bd-a475-11e9-a618-0800275062ed 8Gi RWO standard 13m
-
Identify the PC
shell% kubectl get pv NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE pvc-66bb97bd-a475-11e9-a618-0800275062ed 8Gi RWO Delete Bound default/my-ci-jenkins standard 13m
Changing the Retain Policy
If you want to re-use the same PVC and PV, you must change the value of the Retain Policy. This is to prevent the volume from being deleted if the deployment is regenerated during the migration.
-
Issue the command
kubectl get pv
, and check the value of theRECLAIM POLICY
column in the output. -
If the Reclaim Policy is set to anything other than
Retain
, patch the PV with the commandkubectl patch
, substituting the appropriatePV-NAME
from the output of thekubectl get pv
command:shell% kubectl patch pv PV-NAME -p '"spec":"persistentVolumeReclaimPolicy":"Retain"}}'
-
To verify that the patch has been applied, run the
kubectl get pv
command again and confirm that the value of the Retain Policy is nowRetain
.
Making the PVC selectable
The CloudBees Jenkins Distribution deployment uses the values of two labels to select the objects that are associated with the pod:
-
"app.kubernetes.io/instance": "{{ .Release.Name }}"
-
"jenkins.instance": "cjd"
{{ .Release.Name }}
is the name given to the release when the Jenkins deployment is installed by helm. If you’re not sure what value the label should have, issue the command helm list
to display the list of releases installed on your cluster.
To confirm that the PVC has set the proper labels:
-
Issue the
kubectl describe pvc
command, substituting the appropriatePVC-NAME
from the output of thekubectl get pvc
command. Thekubectl describe pvc
command retrieves the description of the PVC, which provides the labels (if any) for this object:shell% kubectl describe pvc PVC-NAME Name: my-ci-jenkins Namespace: default StorageClass: standard Status: Bound Volume: pvc-66bb97bd-a475-11e9-a618-0800275062ed Labels: app.kubernetes.io/component=jenkins-master app.kubernetes.io/instance=my-ci app.kubernetes.io/managed-by=Tiller app.kubernetes.io/name=jenkins helm.sh/chart=jenkins-1.1.18 Annotations: control-plane.alpha.kubernetes.io/leader: {"holderIdentity":"9eee62df-a474-11e9-a5ff-0800275062ed","leaseDurationSeconds":15,"acquireTime":"2019-07-12T07:19:35Z","renewTime":"2019-... pv.kubernetes.io/bind-completed: yes pv.kubernetes.io/bound-by-controller: yes Finalizers: [kubernetes.io/pvc-protection] Capacity: 8Gi Access Modes: RWO VolumeMode: Filesystem Mounted By: my-ci-jenkins-69897b85bd-ff7bn Events: Type Reason Age From Message ---- ------ --- ---- ------- Normal Provisioning 14m k8s.io/minikube-hostpath 9eee62df-a474-11e9-a5ff-0800275062ed External provisioner is provisioning volume for claim "default/my-ci-jenkins" Normal ProvisioningSucceeded 14m k8s.io/minikube-hostpath 9eee62df-a474-11e9-a5ff-0800275062ed Successfully provisioned volume pvc-66bb97bd-a475-11e9-a618-0800275062ed
-
If any of the labels are missing, issue the
kubectl label pvc
command, substituting the appropriatePVC-NAME
from the output of thekubectl get pvc
command.kubectl label pvc
updates the PVC with the values you provide forLABEL-NAME
andLABEL-VALUE
:shell% kubectl label pvc PVC-NAME LABEL-NAME=LABEL-VALUE
Changing the Jenkins home location
The Jenkins home location must be changed because CloudBees Jenkins Distribution uses a different location than the Jenkins LTS.
To change the Jenkins home location:
-
Create a temporary directory on your local workstation, because you can’t directly copy a directory within a cluster into another directory within the same cluster:
shell% mkdir /tmp/jenkins_home_data
-
Use the
kubectl get pods
command to retrieve the list of pods in the Kubernetes cluster:shell% kubectl get pods -A NAMESPACE NAME READY STATUS RESTARTS AGE default cicd-jenkins-74b85c44cc-zsq6r 1/1 Running 0 15m kube-system aws-node-4gz5w 1/1 Running 0 19m kube-system aws-node-5smgn 1/1 Running 0 19m kube-system aws-node-7cjdc 1/1 Running 0 19m kube-system coredns-7bcbfc4774-2j6lj 1/1 Running 0 31m kube-system coredns-7bcbfc4774-cgxrl 1/1 Running 0 31m kube-system kube-proxy-2pkw6 1/1 Running 0 19m kube-system kube-proxy-528n4 1/1 Running 0 19m kube-system kube-proxy-dt4d8 1/1 Running 0 19m kube-system tiller-deploy-54fc6d9ccc-tg7fd 1/1 Running 0 16m
-
Use the
kubectl cp
command to copy the Jenkins home directory to the temporary directory, substituting the appropriateNAMESPACE
andNAME
from the output of thekubectl get pods
command:shell% kubectl cp <NAMESPACE>/<NAME>:/var/jenkins_home /tmp/jenkins_home_data
-
Finally, use the
kubectl cp
command to copy the old Jenkins home information into the new location, again substituting the appropriateNAMESPACE
andNAME
from the output of thekubectl get pods
command:shell% kubectl cp /tmp/jenkins_home_data/ NAMESPACE/POD-NAME:/var/cloudbees-jenkins-distribution
Migrating or upgrading Helm-installed instances
For installations that were installed using Helm, CloudBees strongly recommends delegating the upgrade to Helm as well.
Helm supports many public and private Helm Chart Repositories, and you must add the CloudBees repository to your Helm environment before you can use it:
-
Add the CloudBees Helm Chart Repository to your Helm installation:
shell% helm repo add cloudbees https://charts.cloudbees.com/public/cloudbees
-
Update your local Helm Chart Repository cache, which improves the performance of commands like
helm search
. To update the cache:shell% helm repo update
-
After you’ve added the CloudBees repository and updated the Chart Repository Cache, you can upgrade the instance.
-
Upgrade the instance with the
helm upgrade
command, substituting the appropriatePV-NAME
from the output of thekubectl get pv
command, and providing a value for RELEASE-NAME (if you are uncertain about the instance’s name, use thehelm list
command to retrieve it):The administrative user and password are changed during the migration, because the migration process deletes the former pod and creates a new one. To retain the old values, add --set master.adminUser=PREVIOUS-USER --set master.adminPassword=PREVIOUS-PASSWD
to thehelm upgrade
command.shell% helm upgrade --set persistence.existingClaim=PVC-NAME RELEASE-NAME cloudbees/cloudbees-jenkins-distribution
Migrating or upgrading instances not installed with Helm
CloudBees strongly recommends using Helm to install or upgrade installations. However, if you are using an installation not installed with Helm, there are two options:
Migrating to Helm
To migrate your installation to Helm:
-
Remove all deployment information except the PVC.
-
Change the Jenkins home location as shown in Changing the Jenkins home location.
-
Install the chart using the
helm install
command, substituting the appropriatePV-NAME
from the output of thekubectl get pv
command, and providing a value forRELEASE-NAME
:shell% helm install --set persistence.existingClaim=PVC-NAME RELEASE-NAME cloudbees/cloudbees-jenkins-distribution
Updating the deployment and changing the docker image
There are two ways to edit and update the Docker image used in the Kubernetes cluster:
When you edit or update a Docker image, the Kubernetes cluster discards the current active pod and creates a new one with the new Docker image. |
Editing the deployment online
The first method of changing the Docker image is to directly edit the Kubernetes cluster configuration:
-
Change the Jenkins home location as shown in Changing the Jenkins home location.
-
Use the
kubectl get deployments
command to retrieve the list of pods in the cluster:shell% kubectl get deployments NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE cicd-jenkins 1 1 1 1 20m
-
Use the
kubectl edit deployment
command to open your pre-defined CLI editor (such asvi
orvim
) and edit the deployment’s configuration. Substitute the appropriateNAME
from the output of thekubectl get deployments
command:shell% kubectl edit deployment/NAME
-
In the editor, locate the line that reads
image: jenkins/jenkins:lts
and change it to read
image: cloudbees/cloudbees-jenkins-distribution:latest
-
Next, locate the line that reads
mountPath: /var/jenkins_home
+ and change it to read
mountPath: /var/cloudbees-jenkins-distribution
-
Save the file. The resulting configuration should resemble:
spec: template: spec: containers: - image: cloudbees/cloudbees-jenkins-distribution:latest [...] volumeMounts: - mountPath: /var/cloudbees-jenkins-distribution
-
Use the
kubectl get pods --watch
command to display any changes to the pod status. Because Kubernetes creates a new pod for the new Docker image, the deployment is not actually ready until the status isRunning
.shell% kubectl get pods --watch NAME READY STATUS RESTARTS AGE cicd-jenkins-7c69dbcbb4-wkcz7 0/1 Init:0/1 0 52s cicd-jenkins-7c69dbcbb4-wkcz7 0/1 PodInitializing 0 53s cicd-jenkins-7c69dbcbb4-wkcz7 0/1 Running 0 72s
Patching the deployment directly
The second method involves directly patching the deployment instead of using a CLI editor:
-
Use the
kubectl get deployments
command to retrieve the list of pods in the cluster:shell% kubectl get deployments NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE cicd-jenkins 1 1 1 1 20m
-
Create a
patch.yaml
file in your local file directory. -
Populate
patch.yaml
with the configuration fields you want to change. Substitute the name of the deployment as appropriate, using the output of thekubectl get deployments
command. You can change any configuration field in the deployment, but the recommended minimum patch is:spec: template: spec: containers: - name: <NAME> image: "cloudbees/cloudbees-jenkins-distribution:latest" volumeMounts: - mountPath: /var/cloudbees-jenkins-distribution name: jenkins-home readOnly: false
-
Use the
kubectl patch deployment
command to patch the deployment:shell% kubectl patch deployment DEPLOYMENT-NAME --patch "$(cat patch.yaml)"
-
Use the
kubectl get pods --watch
command to display the pod status changes. Because Kubernetes creates a new pod for the updated Docker image, the deployment is not actually ready until the status isRunning
.shell% kubectl get pods --watch NAME READY STATUS RESTARTS AGE cicd-jenkins-7c69dbcbb4-wkcz7 0/1 Init:0/1 0 52s cicd-jenkins-7c69dbcbb4-wkcz7 0/1 PodInitializing 0 53s cicd-jenkins-7c69dbcbb4-wkcz7 0/1 Running 0 72s
After installation, the Getting Started wizard will walk you through installing a curated set of plugins and creating the first admin account.
Security and unlocking the distribution
CloudBees Jenkins Distribution is initially configured to be secure on first launch. During installation,
a password is generated and saved in a local file called initialAdminPassword
.
The file location depends upon the operating system you are using.
This password is required to unlock the instance on the Unlock Jenkins page.
To locate the password:
-
Open a browser to http://localhost:8080.
-
Open the
initialAdminPassword
file using the location displayed on the Unlock Jenkins page. -
Copy the password from the file.
Alternatively, the password may be displayed during installation. For example, the output below was from installing on macOS using a WAR file:
*************************************************************
*************************************************************
*************************************************************
Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:
d661ea28c6b94406ad627601b6f4aa877
This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword
*************************************************************
*************************************************************
*************************************************************
Registration
During setup, you will be prompted to choose a registration type. You can register with a free product key online or contact CloudBees Support to obtain registration activation.
Using the Getting Started wizard
-
Open a browser to http://localhost:8080.
-
On the Unlock Jenkins page, paste in the Administrator password retrieved in the previous section in the field. Press Continue.
-
Select the appropriate registration option on the License page.
-
Activate CloudBees Jenkins Distribution (requires online activation): Complete the form on Register CloudBees Jenkins Distribution page. Enter your name, email and company, check the box to accept the license agreement and click Submit. The Setup Wizard will contact CloudBees to create a license and apply the license to the product.
-
Use a license key (Apply a valid license key; useful for offline installations): Click Activate CloudBees Jenkins Distribution to obtain a free license (requires internet access). If necessary, contact CloudBees Sales to obtain your existing product registration. Select license key and paste the License Key and License Certificate from your existing registration into the appropriate fields. Review the license and then accept the license by clicking the check box and click Submit.
-
-
Select Install suggested plugins on the Customize Jenkins page to install the curated set of plugins recommended by CloudBees.
-
The Getting Started page displays the setup progress. If any updates are available, you will also be given the option to upgrade. These upgrades may also be performed at a later time using the Beekeeper Upgrade Assistant.
-
On the Create First Admin User page, enter a username, password (twice), full name, and email address for the first admin user. Press Save and Continue.
-
Enter a new value for the Jenkins URL on the Instance Configuration page. You may choose to use the default value or to enter a new URL. Press Save and Finish.
The Jenkins URL provides the root URL for absolute links to various Jenkins resources, including email notifications, PR status updates, and the BUILD_URL environment variable provided to build steps. -
You may be asked to reboot your system.