Running Stash as a Linux service

Redirection notice

This page will redirect to /display/BitbucketServer/Running+Bitbucket+Server+as+a+Linux+service .

  • The Stash installer for Linux installs Stash as a service – see Getting started. The information on this page only applies if you are manually installing or upgrading Stash.
  • System administration tasks are not supported by Atlassian. These instructions are only provided as a guide and may not be up to date with the latest version of your operating system.

For production use on a Linux server, Stash should be configured to run as a Linux service, that is, as a daemon process. This has the following advantages:

  • Stash can be automatically restarted when the operating system restarts.
  • Stash can be automatically restarted if it stops for some reason.
  • Stash is less likely to be accidentally shut down, as can happen if the terminal Stash was manually started in is closed.
  • Logs from the Stash JVM can be properly managed by the service.

This page describes the following approaches to running Stash as a service on Linux:

  • Use the Java Service Wrapper, which allows a Java application to be run as a UNIX daemon.
  • Use an init.d script to start Stash at boot time - this doesn't restart Stash if it stops for some reason.
  • Use a systemd unit file to start Stash at boot time - this doesn't restart Stash if it stops for some reason.

Note that Stash assumes that the external database is available when it starts; these approaches do not support service dependencies, and the startup scripts will not wait for the external database to become available.

On this page:

Using the Java Service Wrapper

Stash can be run as a service on Linux using the Java Service Wrapper. The Service Wrapper is known to work with Debian, Ubuntu, and Red Hat.

The Service Wrapper provides the following benefits:

  • Allows Stash, which is a Java application, to be run as a service.
  • No need for a user to be logged on to the system at all times, or for a command prompt to be open and running on the desktop to be able to run Stash.
  • The ability to run Stash in the background as a service, for improved convenience, system performance and security.
  • Stash is launched automatically on system startup and does not require that a user be logged in. 
  • Users are not able to stop, start, or otherwise tamper with Stash unless they are an administrator.
  • Can provide advanced failover, error recovery, and analysis features to make sure that Stash has the maximum possible uptime.

Please see http://wrapper.tanukisoftware.com/doc/english/launch-nix.html for wrapper installation and configuration instructions.

The service wrapper supports the standard commands for SysV init scripts, so it should work if you just create a symlink to it from /etc/init.d.

Using an init.d script

The usual way on Linux to ensure that a process restarts at system restart is to use an init.d script. This approach does not restart Stash if it stops by itself.

  1. Stop Stash.
  2. Create a stash user, set the permissions to that user, create a home directory for Stash and create a symlink to make upgrades easier:

    $> curl -OL http://downloads.atlassian.com/software/stash/downloads/atlassian-stash-X.Y.Z.tar.gz
    $> tar xz -C /opt -f atlassian-stash-X.Y.Z.tar.gz
    $> ln -s /opt/atlassian-stash-X.Y.Z /opt/atlassian-stash-latest
     
    # Create a home directory
    $> mkdir /opt/stash-home
     
    # ! Update permissions and ownership accordingly

    (Be sure to replace X.Y.Z in the above commands with the version number of Stash.)

  3. Create the startup script in /etc/init.d/stash with the following contents (Ensure the script is executable by running chmod 755 stash):

    #! /bin/sh
    
    ### BEGIN INIT INFO
    # Provides:          stash
    # Required-Start:    $remote_fs $syslog
    # Required-Stop:     $remote_fs $syslog
    # Default-Start:     2 3 4 5
    # Default-Stop:      0 1 6
    # Short-Description: Initscript for Atlassian Stash
    # Description:  Automatically start Atlassian Stash when the system starts up.
    #               Provide commands for manually starting and stopping Stash.
    ### END INIT INFO
    
    # Adapt the following lines to your configuration
    # RUNUSER: The user to run Stash as.
    RUNUSER=vagrant
    
    # STASH_INSTALLDIR: The path to the Stash installation directory
    STASH_INSTALLDIR="/opt/atlassian-stash-X.Y.Z"
    
    # STASH_HOME: Path to the Stash home directory
    STASH_HOME="/opt/stash-home"
    
    # ==================================================================================
    # ==================================================================================
    # ==================================================================================
    
    # PATH should only include /usr/* if it runs after the mountnfs.sh script
    PATH=/sbin:/usr/sbin:/bin:/usr/bin
    DESC="Atlassian Stash"
    NAME=stash
    PIDFILE=$STASH_INSTALLDIR/work/catalina.pid
    SCRIPTNAME=/etc/init.d/$NAME
    
    # Read configuration variable file if it is present
    [ -r /etc/default/$NAME ] && . /etc/default/$NAME
    
    # Define LSB log_* functions.
    # Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
    . /lib/lsb/init-functions
    
    
    run_with_home() {
        if [ "$RUNUSER" != "$USER" ]; then
            su - "$RUNUSER" -c "export STASH_HOME=${STASH_HOME};${STASH_INSTALLDIR}/bin/$1"
        else
            export STASH_HOME=${STASH_HOME};${STASH_INSTALLDIR}/bin/$1
        fi
    }
    
    #
    # Function that starts the daemon/service
    #
    do_start()
    {
        run_with_home start-stash.sh
    }
    
    #
    # Function that stops the daemon/service
    #
    do_stop()
    {
        if [ -e $PIDFILE ]; then
          run_with_home stop-stash.sh
        else
          log_failure_msg "$NAME is not running."
        fi
    }
    
    
    case "$1" in
      start)
        [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
        do_start
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
      stop)
        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
        do_stop
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
      status)
           if [ ! -e $PIDFILE ]; then
             log_failure_msg "$NAME is not running."
             return 1
           fi
           status_of_proc -p $PIDFILE "" $NAME && exit 0 || exit $?
           ;;
      restart|force-reload)
        #
        # If the "reload" option is implemented then remove the
        # 'force-reload' alias
        #
        log_daemon_msg "Restarting $DESC" "$NAME"
        do_stop
        case "$?" in
          0|1)
            do_start
            case "$?" in
                0) log_end_msg 0 ;;
                1) log_end_msg 1 ;; # Old process is still running
                *) log_end_msg 1 ;; # Failed to start
            esac
            ;;
          *)
            # Failed to stop
            log_end_msg 1
            ;;
        esac
        ;;
      *)
        echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2
        exit 3
        ;;
    esac

Running on system boot

  1. To start on system boot, add the script to the start up process.
    For Ubuntu (and other Debian derivatives) use:

    update-rc.d stash defaults


    For RHEL (and derivates) use:

    chkconfig --add stash --level 0356

    Note: You may have to install the redhat-lsb package on RHEL (or derivatives) to provide the LSB functions used in the script.

  2. Verify that the Stash service comes back up after restarting the machine.

Using a systemd unit file

Thanks to Patrick Nelson for calling out this approach, which he set up for a Fedora system. It also works on other distributions that use systemd as the init system. This approach does not restart Stash if it stops by itself.

  1. Create a stash.service file in your /etc/systemd/system/ directory with the following lines:

    [Unit]
    Description=Atlassian Stash Service
    After=syslog.target network.target
     
    [Service]
    Type=forking
    User=atlstash
    ExecStart=/opt/atlassian-stash-X.Y.Z/bin/start-stash.sh
    ExecStop=/opt/atlassian-stash-X.Y.Z/bin/stop-stash.sh
     
    [Install]
    WantedBy=multi-user.target


    The value for User should be adjusted to match the user that Stash runs as. ExecStart and ExecStop should be adjusted to match the path to your <Stash installation directory>.

  2. Enable the service to start at boot time by running the following in a terminal:

    systemctl enable stash.service
  3. Stop Stash, then restart the system, to check that Stash starts as expected.
  4. Use the following commands to manage the service:
    Disable the service:
    systemctl disable stash.service
    Check that the service is set to start at boot time:
    if [ -f /etc/systemd/system/*.wants/stash.service ]; then echo "On"; else echo "Off"; fi
    Manually start and stop the service: 
    systemctl start stash
    systemctl stop stash
    Check the status of Stash:
    systemctl status stash

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport