Installing Subsonic

Requirements: Java 6 or later (Download)

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.

Requirements: Sun Java 5 or later (Download)

This is Subsonic with an embedded Jetty server. Recommended for most Linux and Mac users.

• 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:8080.

Requirements: Java 5 or later (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.
• Post a message to the Subsonic forum. Please let us know what Subsonic version, Tomcat version and operating system you're using. Also, please give a detailed description of the problem. This way, we'll be able to help you faster.