# Stash Latest (2.12) : Installing Stash on Linux and Mac

Created and last modified by pwatson on Apr 02, 2014

Hey! We're going to install Stash on a Linux box, or a Mac. There are a few steps, but we think you'll really like Stash once it's up and running.

If you are installing Stash for production or enterprise use, first check the additional steps at the bottom of this page and read Using Stash in the enterprise.

### 1. Check supported platforms

Better check the Supported platforms page first; it lists the application servers, databases, operating systems, web browsers and Java 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.

Related pages:

- Installing Stash on Windows
- Running Stash as a Linux service
- Getting started with Git and Stash
- Supported platforms
- Stash upgrade guide
- Using Stash in the enterprise

See also:

- Chef recipe for Stash
- Puppet/Vagrant How-To

### 2. Check your version of Java

In a terminal, run this:

    java -version

The version of Java should be 1.7.x (Java 1.8 is not supported yet).

If you don't see Java 1.7.x then get Java...

### Install Java

Download Java Server JRE from Oracle's website, and install it (note that Java 1.8 is not supported by Stash yet).

Now try running '`java -version`' again to check the installation. The version of Java should be 1.7.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/`.

### Set your JAVA_HOME if you don't see a path

Linux | Mac
--- | ---
Do either 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: `/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/` 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: `JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/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, like this: `java version "1.7.0_1"`

### 3. Check your versions of Git and Perl

In a terminal, run this:

    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...

Download and install the latest stable Git release from the Git website.

Now try running '`git --version`' again. The version of Git should be 1.7.6 or higher.

Please note the following:

- See the Git resources page for links to more Git download sites.
- At the time of writing, the default Git version on Ubuntu Linux is 1.7.5.x, which is too old for Stash: see https://launchpad.net/~git-core/+archive/ppa.

- At the time of writing, on Mac OS X, the Git tar archive can fail on special characters when using SSH to secure connections between your computer and Stash. (The Git `archive` command allows you to download as a single file the files in a checkout of the Git repository.) We recommend that you use the zip format; you can set that using the following command:

      git archive --format zip

Download and install the latest stable Perl release from http://www.perl.org/get.html, or use your favourite package manager.

Now try running '`perl` `--version`' again. The version of Perl should be 5.8.8 or higher.

### 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. The path to the extracted directory is referred to as the``<Stash installation directory>`` in these instructions. 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.

### 5. Tell Stash where to store your data

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

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.sh` 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:

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 will 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.

### 6. Start Stash!

In a terminal, change directory to `<Stash installation directory>` and run this:

    bin/start-stash.sh

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

- Select Internal at the 'Database' step, if you are evaluating Stash. Stash will happily use its internal database, and you can easily migrate to external database later. See Connecting Stash to an external database.
- You can set up JIRA integration, but you can do this later if you wish. See Configuring JIRA integration in the Setup Wizard .

### 7. 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.

### 8. 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:

- Getting started with Git and Stash
- Importing code from an existing project

## Additional steps for production environments

For production or enterprise environments we recommend that you configure the additional aspects below. These are not necessary when installing for evaluation purposes. Please see Using Stash in the enterprise for more information about best practice.

##### Install and run Stash as a dedicated user

- For production environments Stash should be run from a dedicated user account with restricted privileges. See Running Stash with a dedicated user.

##### Use an external database

- For production environments Stash should use an external database, rather than the embedded database. See Connecting Stash to an external database.

##### Secure the Stash home directory

- For production environments the Stash home directory (created in step 7 above) should be secured against unauthorised access. See Stash home directory.

##### Secure Stash with HTTPS

- For production environments access to Stash should be secured using HTTP over SSL, especially if your data is sensitive and Stash is exposed to the internet. See Securing Stash with Tomcat using SSL.

##### Connect to your existing user directory

- See External user directories.

##### Change the context path for Stash

- Where y ou are running Stash behind a proxy, or you have another Atlassian application (or any Java web application) available at the same hostname and context path as Stash, then you should set a unique context path for Stash. See Moving Stash to a different context path.

##### Install Stash as a service

- See Running Stash as a Linux service

### Stopping Stash (optional)

In a terminal, change directory to `<Stash installation directory>` and run this:

    bin/stop-stash.sh

## Uninstalling Stash

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

## Attachments:

Stash_1_0_stash_home.png (image/png)
Stash_1_0_stash_home.png (image/png)
Stash_1_0_stash_home.png (image/png)
Stash_1_0_stash_home.png (image/png)
Stash_1_0_stash_home.png (image/png)