How to Install

Windows installation Mac installation Debian / Ubuntu installation
Red Hat / Fedora installation Stand-alone installation WAR installation

Important! Immediately after installing Subsonic you should change the admin password to secure the server. Point your browser to the Subsonic web page (see URL below), and log in with username admin and password admin. Go to Settings > Users to change password and create new users.

Windows installation

On Windows, the easiest way to install Subsonic is using the provided Windows Installer: subsonic-x.x-setup.exe.

It installs Subsonic as a service, available in Control Panel > Administrative Tools > Services, that is started automatically when you log on to Windows.

It also creates links in the Start Menu: Start > All Programs > Subsonic. From this menu you can start/stop the Subsonic service, open the Subsonic web page, or change basic settings such as which port number Subsonic should use. You can also click on the little yellow submarine tray icon.

If you're upgrading an existing Subsonic installation, you don't have to uninstall the old version first. In any case, the existing Subsonic settings are preserved.

After installing and starting Subsonic, open the Subsonic web page on http://localhost:4040.

Mac installation

Download the installation package and run it. This installs Subsonic.app in Applications. Start it by opening Applications and click the Subsonic icon. A small headset icon will appear in the menu bar. If you want Subsonic to start automatically when you log in, open System Preferences > Users & Groups and add Subsonic to the list of Login Items.

After installing and starting Subsonic, open the Subsonic web page on http://localhost:4040.

Advanced configuration

To change the port number, Java memory settings or other startup parameters, edit /Applications/Subsonic.app/Contents/Info.plist.

Troubleshooting

If Subsonic doesn't start properly you can troubleshoot it by starting it from the command line: /Applications/Subsonic.app/Contents/MacOS/JavaAppLauncher.

Also check the logs in /Library/Application Support/Subsonic.

Debian / Ubuntu installation

This installation option applies to Debian Linux, including Ubuntu.

  • First, install Java: sudo apt-get install openjdk-8-jre
  • Download the Subsonic .deb package and install it: sudo dpkg -i subsonic-x.x.deb

Notice that the installer configures your system to start Subsonic automatically when booting. After installing, open the Subsonic web page on http://localhost:4040.

Change user

By default the Subsonic process is run as the root user. To improve security it is strongly advised that you run it as a dedicated user with less powerful privileges. You can specify this user by setting the SUBSONIC_USER variable in /etc/default/subsonic.

Note that non-root users are by default not allowed to use ports below 1024. Also make sure to grant the user write permissions in the music directories, otherwise changing album art and tags will fail.

Advanced configuration

To change the port number, Java memory settings or other startup parameters, edit the SUBSONIC_ARGS variable in /etc/default/subsonic. To restart Subsonic, do sudo service subsonic restart

Troubleshooting

Check the logs in /var/subsonic.

Red Hat / Fedora installation

This installation option applies to Red Hat Linux, including Fedora.

  • First, install Java: sudo yum install java-1.8.0-openjdk
  • Download the Subsonic .rpm installation package and install it: sudo yum install --nogpgcheck subsonic-x.x.rpm
  • If nothing happens, try to remove the old version first (all settings will be retained): sudo yum remove subsonic

Notice that the installer configures your system to start Subsonic automatically when booting. After installing, open the Subsonic web page on http://localhost:4040.

Change user

By default the Subsonic process is run as the root user. To improve security it is strongly advised that you run it as a dedicated user with less powerful privileges. You can specify this user by setting the SUBSONIC_USER variable in /etc/sysconfig/subsonic.

Note that non-root users are by default not allowed to use ports below 1024. Also make sure to grant the user write permissions in the music directories, otherwise changing album art and tags will fail.

Advanced configuration

To change the port number, Java memory settings or other startup parameters, edit the SUBSONIC_ARGS variable in /etc/sysconfig/subsonic. To restart Subsonic, do sudo service subsonic restart

Troubleshooting

Check the logs in /var/subsonic.

Stand-alone installation

Requirements: Java 8 (Download)

This is Subsonic with an embedded Jetty server, and can be installed on any Windows, Linux, Unix, FreeNAS, unRAID etc operating system.

  • Unpack subsonic-x.x-standalone.tar.gz to SUBSONIC_HOME/standalone. SUBSONIC_HOME is typically c:\subsonic on Windows, and /var/subsonic on Unix-based operating systems.
  • Optionally configure the startup script SUBSONIC_HOME/standalone/subsonic.sh
  • Execute the startup script. (Typically you will configure your operating system to execute the script automatically at start-up.)
  • Open the Subsonic web page. The default address is http://localhost:4040.

WAR installation

Requirements: Java 8 (Download). A servlet container supporting Servlet 2.4 and JSP 2.0.

Use this option if you want to deploy Subsonic in an external server, such as Tomcat, Jetty, GlassFish or Geronimo. Subsonic comes packaged as a standard Java web application, subsonic.war, which can be easily deployed in any compatible servlet container. The most commonly used server is Tomcat, and the rest of this section describes how to install or upgrade Subsonic on a Tomcat server.

  • Stop Tomcat if it's running.
  • Remove these files and directories if they exist:
    • TOMCAT_HOME/webapps/subsonic.war
    • TOMCAT_HOME/webapps/subsonic
    • TOMCAT_HOME/work
  • Copy the file subsonic.war to TOMCAT_HOME/webapps.
  • Start Tomcat.
  • Point your web browser to http://localhost/subsonic (or http://localhost:8080/subsonic if you installed Tomcat on port 8080.)

Notes

  • If you installed Tomcat as a Windows Service, you can start and stop it from the service manager: Control Panel > Administrative Tools > Services.
  • TOMCAT_HOME refers to the directory in which you installed Tomcat. On Windows this is normally C:\Program Files\Apache Software Foundation\Tomcat 5.5
  • On Linux, Subsonic keeps its files in /var/subsonic. Depending on your configuration, Tomcat may not be permitted to create this directory, in which case you have to create it manually: mkdir /var/subsonic; chown tomcat:tomcat /var/subsonic

Troubleshooting

If you experience any problems, please make sure you follow the installation instructions above. Here's a list of suggestions of what to do if it still doesn't work:

  • Restart Tomcat.
  • Reinstall Subsonic.
  • Upgrade to the latest Tomcat version (at least if you're using Tomcat 5.0 or earlier).
  • Look for errors in the Subsonic log, c:\subsonic\subsonic.log or /var/subsonic/subsonic.log.
  • Look for errors in the Tomcat logs, TOMCAT_HOME/logs.