Upgrading from Hudson to Jenkins

Skip to end of metadata
Go to start of metadata

Table of Contents

This page discusses how you upgrade from Hudson to Jenkins.

Migration is only supported from Hudson ≤ 1.395

Before you begin

Please make a backup, especially the Hudson home directory, that contains the most important information, such as jobs, configuration and build history. In the unlikely event that something goes wrong you can recover from the backup.

When you are actually migrating


Jenkins is basically a drop-in replacement to Hudson. It's the continuation of the same code base, in same package structure. There has been no major surgery since the rename, and the rename really only affected what's shown in the UI. As such, it understands the same set of environment variables, same system properties, and the same information in the home directory. So if you rename jenkins.war as hudson.war, and simply overwrite your hudson.war, the upgrade is complete.

Jenkins does not support cascading projects yet. See JENKINS-3157

Debian package

Current users of the Hudson debian package should follow the instruction here for the new users. When you do "apt-get install jenkins", it will uninstall the hudson package, transfer your /var/lib/hudson to /var/lib/jenkins.

  • A few users have reported losing their /var/lib/hudson data in the upgrade. Please make a backup before upgrading till the report can be sorted out.
    • Check your /etc/default/hudson for the HUDSON_HOME to backup
  • Note that Jenkins run as the jenkins user. If you have scripts and other automation that hard-codes the user name, they'll need to be updated.
    • If you are using the unix based authentication system, make sure that you add the jenkins user to the shadow group or you won't be able to log in.
  • If your /var/lib/hudson is big, it may take some time for the post-init script to do chown.
  • What used to be in /etc/default/hudson is now in /etc/default/jenkins. If you've made changes to this configuration file, you need to manually reflect those into /etc/default/jenkins.
  • If your HUDSON_HOME was not in /var/lib/hudson, you need to manually chown your HUDSON_HOME to the jenkins user and update /etc/default/jenkins.
If you don't want the jenkins package to touch /var/lib/hudson or if you'd like to keep the hudson user to run Jenkins, rename /var/lib/hudson to /var/lib/hudso_ before the jenkins installation, then after the package has finished installing, move /var/lib/hudso_ back to /var/lib/hudson and change /etc/default/jenkins to run as the hudson user.

RedHat/openSUSE packages

Current users of the Hudson rpm package should follow the instruction here (Red Hat) or here (openSUSE) for the new users. When you do "yum install jenkins" or "zypper install jenkins", it will uninstall the hudson package, transfer your /var/lib/hudson to /var/lib/jenkins.

See the caution about the Debian package above, with regard to what happens to /var/lib/hudson and the hudson user. In RPM packages, the configuration file is in /etc/sysconfig/... instead of /etc/default/....

There's a bug in the shutdown portion of /etc/init.d/hudson and Hudson fails to stop itself when it's removed. So check if the process is still running, and kill it if necessary before starting jenkins.

Installed as Windows service

If you've installed Hudson as a Windows service, stop the service and overwrite hudson.war with jenkins.war, and restart the service. No additional steps are necessary.

If you prefer, you can uninstall Hudson as a service (by executing hudson.exe uninstall which produces no output on successful execution), and re-install Jenkins as a service from GUI. During this process you'll be asked to specify the installation directory. Choose the same directory you've installed Hudson so that your data gets carried over.

Installed in servlet container

If you've installed hudson.war into a servlet container that you administer, download jenkins.war and deploy it as hudson.war.

If you prefer, you can just undeploy hudson.war and deploy jenkins.war. Jenkins recognizes HUDSON_HOME environment variable and system property, so it'll automatically find your existing data.

Jenkins pick up its home folder via various configuration parameters. Its precedence is as follows (higher first):
  1. JNDI environment entry called JENKINS_HOME
  2. JNDI environment entry called HUDSON_HOME
  3. System property named JENKINS_HOME
  4. System property named HUDSON_HOME
  5. Environment variable named JENKINS_HOME
  6. Environment variable named HUDSON_HOME
  7. System.getProperty("user.home")+"/.hudson" if it already exists
  8. System.getProperty("user.home")+"/.jenkins"

If you are thinking about upgrading to Jenkins but not ready to do so now

You can install Jenkins update center in your Hudson so that you get update notifications of future Jenkins releases. You can use the built-in upgrade mechanism in Hudson to smoothly migrate to Jenkins. To do so, go to "Manage Hudson" > "Plugin Management" > "Advanced" > "Update Site" and specify "http://updates.jenkins-ci.org/update-center.json"

After upgrading

While you are at it, please check this document and retrieve/create your account on jenkins-ci.org, so that you can file issues, participate in Wiki, and so on.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment