Upgrade Bitbucket Server from an archive file
This article describes how to upgrade Bitbucket Server, the product formerly known as Stash. Read more about the name change.
This page describes how to manually upgrade Bitbucket Server from an archive file. However, we strongly recommend that you use the Bitbucket Server installer instead, for a quick and trouble-free upgrade experience.
You may be interested in this alternative provisioning approach:
1. Check supported platforms
Check the Supported platforms page for details of the application servers, databases, operating systems, web browsers and Java and Git versions that we have tested Bitbucket Server with and recommend.
Atlassian only officially supports Bitbucket Server running on x86 hardware and 64-bit derivatives of x86 hardware.
Cygwin Git is not supported. No internal testing is done on that platform, and many aspects of Bitbucket Server's functionality (pull requests and forks among them) have known issues. When running Bitbucket Server on Windows, always use msysGit.
2. Check your version of Java
In a terminal or command prompt, run this:
java -version
The version of Java should be 1.8.x. You'll need a 64-bit version of Java if you have a 64-bit operating system.
3. Check your version of Git
In a terminal or command prompt, run:
git --version
The version of Git should be 1.8.x or higher.
If you are running an earlier version of Git you will need to upgrade to a later version – see Installing and upgrading Git for assistance.
4. Get the latest version of Bitbucket Server
Download Bitbucket Server from the Atlassian download site. Looking for the Bitbucket Server WAR file?
Extract the downloaded file to an install location (without spaces in the path).
The path to the extracted directory is referred to as the
in these instructions.<Bitbucket Server installation directory>
Never unzip the Bitbucket Server archive file over the top of an existing Bitbucket Server installation – each version of Bitbucket Server includes versioned jar files, such as bitbucket-model-4.0.0.jar
. If you copy these, you end up with multiple versions of Bitbucket Server's jar files in the classpath, which leads to runtime corruption.
Note that you should use the same user account to both extract Bitbucket Server and to run Bitbucket Server (in Step 6.) to avoid possible permission issues at startup. For production installations, we recommend that you create a new dedicated user that will run Bitbucket Server on your system. See Running Bitbucket Server with a dedicated user.
5. Tell Bitbucket Server where your data is stored
The Bitbucket Server home directory is where your Bitbucket Server data is stored. You need to update the value of BITBUCKET_HOME
in the <Bitbucket Server installation directory
>/bin/setenv
file so the new Bitbucket Server installation points to your existing Bitbucket Server home directory (if you use a BITBUCKET_HOME
environment variable to specify the home directory location, no change is required).
6. Make changes to server.xml
If you are upgrading from Stash 3.7 or earlier and you have made custom changes to the
server.xml
file in your installation, you have to make those changes in the server.xml
file of your new installation as well, which is in a different location as of Stash 3.8. You would have made these changes if you modified the port, context path, or the access protocol, or if you are running Bitbucket Server behind a proxy and modified the Connector element.
Locating the server.xml file
The location of the server.xml
file changed in Stash 3.8 to keep editable configuration files in the Bitbucket home directory and out of the (version specific) installation directories.
Release | Directory |
---|---|
Stash 3.7 and earlier | <Stash installation directory>/ conf/server.xml |
Stash 3.8 and later | <Stash home directory> /shared/server.xml |
Bitbucket Server 4.0 and later | <Bitbucket home directory> /shared/server.xml
|
Upgrading from Stash to Bitbucket Server
When upgrading from Stash to Bitbucket Server you must rename references from atlassian-stash
to atlassian-bitbucket
within the server.xml
file. The reference will be in the following element.
Stash 3.x reference |
|
---|---|
Bitbucket Server 4.x reference |
|
7. Create the atlbitbucket dedicated user account
You should create a new dedicated user account to run Bitbucket Server named atlbitbucket
following the instructions outlined in Running Bitbucket Server with a dedicated user.
8. Start Bitbucket Server
There are a couple of ways in which you can start Bitbucket Server – see Starting and stopping Bitbucket Server.