Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

To install Stash yourself...

... from an archive file, on Linux, Mac OS X or Windows, read on!

Use the installer instead...

... for a quick and trouble-free install.
See Getting started.

For production installs...

... we highly recommend that you first read Using Stash in the enterprise.

This page describes how to manually install Stash from an archive file. However, we strongly recommend that you use the Stash installer instead, for a quick and trouble-free install experience.

You may be interested in these alternative provisioning approaches:

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 Stash with and recommend.

Atlassian only officially supports Stash 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 Stash's functionality (pull requests and forks among them) have known issues. When running Stash 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.7.x or 1.8.x. You'll need a 64-bit version of Java if you have a 64-bit operating system.

Install Java

Download Java Server JRE from Oracle's website, and install it.

Now try running 'java -version' again to check the installation. The version of Java should be 1.7.x  or 1.8.x.

Check that the system can find Java

In a terminal, run this:

echo $JAVA_HOME

You should see a path like /usr/jdk/jdk1.7.0.

If you don't see a path, then set JAVA_HOME

Do one of the following:

  • If JAVA_HOME is not set, log in with 'root' level permissions and run:

    echo JAVA_HOME="path/to/JAVA_HOME" >> /etc/environment

    where path/to/JAVA_HOME may be like: /usr/jdk/jdk1.7.0

  • If JAVA_HOME needs to be changed, open the  /etc/environment file in a text editor and modify the value for JAVA_HOME to:
    JAVA_HOME="path/to/JAVA_HOME"

    It should look like: /usr/jdk/jdk1.7.0

Install Java

Download Java Server JRE from Oracle's website, and install it.

Now try running 'java -version' again to check the installation. The version of Java should be 1.7.x or 1.8.x.

Check that the system can find Java

In a terminal, run this:

echo $JAVA_HOME
You should see a path like /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/.

If you don't see a path, then set JAVA_HOME

Open your ~/.profile file in a text editor and insert:

JAVA_HOME="path/to/JAVA_HOME"
export JAVA_HOME

where path/to/JAVA_HOME may be like: /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/

Refresh your ~/.profile in the terminal and confirm that JAVA_HOME is set:

source ~/.profile
$JAVA_HOME/bin/java -version

You should see a version of Java that is 1.7.x or 1.8.x, like this:

java version "1.7.0_1"

Install Java

Download Java Server JRE from Oracle's website, and install it.

Now try running 'java -version' again to check the installation. The version of Java should be 1.7.x or 1.8.x.

Check that the system can find Java

Stash uses the JAVA_HOME environment variable to find Java. To check that, in a command prompt, run:

echo %JAVA_HOME%

You should see a path to the root directory of the Java installation. When running Stash on Windows, unlike Linux or Unix, JAVA_HOME paths with spaces are just fine.

If you don't see a path, then set JAVA_HOME

Stage 1. Locate the JRE installation directory

If you already know the installation path for the Java Runtime Environment, go to Stage 2 below. Otherwise, find the installation path by following these instructions:

  1. If you didn't change the installation path for the Java Runtime Environment during installation, it will be in a directory under C:\Program Files\Java. Using Explorer, open the directory C:\Program Files\Java.
  2. Inside that path will be one or more subdirectories such as C:\Program Files\Java\jre7. 

Stage 2. Set the JAVA_HOME variable

  1. Go to Start, search for "sys env" and choose Edit the system environment variables.
  2. Click Environment Variables, and then New under 'System variables'.
  3. Enter "JAVA_HOME" as the Variable name, and the absolute path to where you installed Java as the Variable value. Don't use a trailing backslash, and don't wrap the value in quotes.

Now, in a new command prompt,  try running '%JAVA_HOME%\bin\java -version'. You should see the same version of Java as you saw in 2. above.

Stage 1. Locate the JRE installation directory

If you already know the installation path for the Java Runtime Environment, go to Stage 2 below. Otherwise, find the installation path by following these instructions:

  1. If you didn't change the installation path for the Java Runtime Environment during installation, it will be in a directory under C:\Program Files\Java. Using Explorer, open the directory C:\Program Files\Java.
  2. Inside that path will be one or more subdirectories such as C:\Program Files\Java\jre7. 

Stage 2. Set the JAVA_HOME variable

Once you have identified the JRE installation path:

  1. Right-click the My Computer icon on your desktop and select Properties.
  2. Click the Advanced tab.
  3. Click the Environment Variables button.
  4. Under System Variables, click New.
  5. Enter the variable name as JAVA_HOME.
  6. Enter the variable value as the installation path for the Java Development Kit. Don't use a trailing backslash, and don't wrap the value in quotes.

    • If your Java installation directory has a space in its path name, you should use the shortened path name (e.g. C:\Progra~1\Java\jre7) in the environment variable instead.

      Note for Windows users on 64-bit systems

      Progra~1 = 'Program Files'
      Progra~2 = 'Program Files(x86)'

  7. Click OK.
  8. Click Apply Changes.
  9. Close any command window which was open before you made these changes, and open a new command window. There is no way to reload environment variables from an active command prompt. If the changes do not take effect even after reopening the command window, restart Windows.

Now, in a new command prompt,  try running '%JAVA_HOME%\bin\java -version'. You should see the same version of Java as you saw in 2. above.

3. Check your versions of Git and Perl

In a terminal or command prompt, run:

git --version
perl --version

The version of Git should be 1.7.6 or higher. The version of Perl should be 5.8.8 or higher.

If you don't see supported versions of Git and Perl, either install or upgrade them – see Installing and upgrading Git.

4. Now it's time to get Stash  

Download Stash from the Atlassian download site. Looking for the Stash 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 <Stash installation directory> in these instructions.

Never unzip the Stash archive file over the top of an existing Stash installation –  each version of Stash includes versioned jar files, such as  stash-model-2.4.1.jar . If you copy these, you end up with multiple versions of Stash's jar files in the classpath, which leads to runtime corruption.

Note that you should use the same user account to both extract Stash and to run Stash (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 Stash on your system. See Running Stash with a dedicated user.

5. Tell Stash where to store your data

The Stash home directory is where your Stash data is stored.

If you are upgrading Stash, simply update the value of STASH_HOME in the <Stash installation directory>/bin/setenv file so the new Stash installation points to your existing Stash home directory (if you use a STASH_HOME environment variable to specify the home directory location, no change is required).

Otherwise, for a new install, create your Stash home directory (without spaces in the name), and then tell Stash where you created it by editing the <Stash installation directory>/bin/setenv file – uncomment the STASH_HOME line and add the absolute path to your home directory. Here's an example of what that could look like when you're done:

(warning) You should not locate your Stash home directory inside the  <Stash installation directory> — they should be entirely separate locations. If you do put the home directory in the <Stash installation directory> it may be overwritten, and lost, when Stash gets upgraded. And by the way, you'll need separate Stash home directories if you want to run multiple instances of Stash.

Tell Stash where you created it by setting a STASH_HOME environment variable, for Windows 7, as follows:

  1. Go to Start, search for "sys env" and choose Edit the system environment variables.
  2. Click Environment Variables, and then New under 'System variables'.
  3. Enter "STASH_HOME" as the Variable name, and the absolute path to your Stash home directory as the Variable value. Don't use a trailing backslash.

There are a few things to know about setting up the Stash home directory on Windows that will make life easier:

6. Move server.xml to your Stash home shared directory

Starting with Stash 3.8, the server.xml file (which, among other things, configures which port Stash serves web requests on) should be located in the shared directory of your Stash home. When you unzip/untar the Stash installation archive server.xml will be located in <Stash installation directory>/conf. You should move this to the shared directory of your Stash home ensuring it is readable by the user account which will run Stash.

If you leave it in <Stash installation directory>/conf Stash will still read it but when you upgrade to new versions you will have to remember to copy it across to the new Stash installation directory. Much easier is to keep it in the shared directory of your Stash home as it will not have to be moved for each upgrade.

7. Start Stash!

There are a couple of ways in which you can start Stash – see Starting and stopping Stash.

Now, in your browser, go to http://localhost:7990 and run through the Setup Wizard. In the Setup Wizard:

8. Set up your mail server

Configure your email server so users can receive a link from Stash that lets them generate their own passwords. See Setting up your mail server.

9. Add users and repositories

Now is the time to set up your users in Stash, and to tell Stash about any existing repositories you have. Please the following pages for the details:

Additional steps for production environments

For production or enterprise environments we recommend that you configure the additional aspects described on Using Stash in the enterprise. The aspects described there are not necessary when you are installing for evaluation purposes only.

If you wish to install Stash as a service on Linux or Windows, see either of:

Stopping Stash

See Starting and stopping Stash.

Uninstalling Stash

To uninstall Stash, stop Stash as described above and then delete the <Stash installation directory> and Stash home directory.

  • No labels
 

 

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.