[Tutorial] The Complete Guide for Installing Your Own Subsonic Music Streaming Server

IMPORTANT: This guide is continually updated from time to time.


  • Guide to setting up transcoding.
  • Changing the subsonic source code and compile.


Subsonic (or Subsonic Music Streamer) is an open source media player server that allows even normal user to share their multimedia files online. The following tutorial is prepared to guide you to fresh install SubSonic mods such as MusicCabinet and Madsonic on Mac OS X. The setup is done on a Mountain Lion 10.8.2 system.

At the end of this tutorial you will:
  • Have a Subsonic streaming server setup on your Mac.
  • Setup Subsonic registration engine so that other user can register without manually creating the users.


  • Java 7
  • Tomcat 6
  • Postgre
  • Macports
Before you proceed with this tutorial, you must make sure that you have the aforementioned components setup. This guide will cover the installation of Tomcat and Postgre as well.

You will have to download the installer from Oracle to install the latest Java 7 as it is not distributed by Apple.

NOTE: The latest Java version distributed by Apple is Java 6, which doesn’t meet the minimum requirements of Subsonic.

The mods might comes with two distribution, namely:
  • Standalone - Bundle together with Jetty Web Server. This is the easiest deployment. 
  • WAR (Web Archive) format - To be deployed on a Java Web Server such as Tomcat. More complicated.

Method 1 - Standalone Deployment (e.g. Music Cabinet)

1. Download the latest standalone deployment here at http://forum.subsonic.org/forum/viewforum.php?f=11

2. Extract it to somewhere convenient, e.g. /Desktop and change your working directory there

cd /Desktop/subsonic-installer-standalone

3. The archive file normally have name such as subsonic-installer-standalone which contains files such as subsonic.war, subsonic-booter-jar-with-dependencies.jar, subsonic.bat (startfup script for windows) and subsonic.sh (startup script for *NIX/Mac)

4. Before launching the startup script, you will need to assign +x rights to the subsonic.sh file.
sudo chmod +x subsonic.sh

5. Create a new directory called /subsonic under /var/ and assign the ownership to it. This directory is used to store subsonic database and log files.
$ sudo mkdir /var/subsonic
$ sudo chown dsync /var/subsonic

6. Launch the script by entering:

7. Access the page by going to http://localhost:4040. You should see a login page.

8. Log in using the default admin account using ‘admin’ for both the username and password.

9. You should see a getting started page that require you to have a Postgre database setup. Proceed here install Postgre if you haven’t got it setup.

10. After setting it up, click on the Configure System. You will be asked to enter a password for the user ‘postgres’. The default password is ‘postgres’ if you installed it using the installation guide on step 8. Otherwise enter the password that you supplied when installing PostgreSQL.

11. That’s it, you’re done.

Method 2 - WAR deployment using Tomcat

Currently it is stated in the site that Subsonic only works well on Tomcat version 6. So this tutorial will proceed to install with Tomcat 6.

1. Refer to the guide (http://wolfpaulus.com/journal/mac/tomcat7)

2. To start the server, simply type:
$ /Library/Tomcat/bin/startup.sh
or the following to stop the server:
$ /Library/Tomcat/bin/shutdown.sh

3. To check which JRE that Tomcat is running, enter (http://localhost:8080) and click the Manager.

4. By default, there isn’t any user created to access the manager interface. You will need to create it by editing:
$ nano /Library/Tomcat/conf/tomcat-users.xml

Then paste the following code just above the '<'/tomcat-users'>'. This will create a user with the name ‘tomcat’ and password ‘s3cret’.
<role rolename="manager-gui">
<user password="s3cret" roles="manager-gui" username="tomcat">

5. Now click the Status and make sure the JVM running is 1.7+. If it is running on version 1.6.x or below, refer here.

6. After making sure that Tomcat is running using JVM version 1.7.x, move the .war file to the following path:
$ mv /Desktop/subsonic.war /usr/local/apache-tomcat-6.0.35/webapps

7. Restart and run the server again. If all goes well you will see the page loading at http://localhost:8080/subsonic

Installing PostgreSQL 9.2

There are two ways of installing it, one is to directly using the .pkg installer found on Postgre official site. The second one is through MacPorts. This tutorial will cover the second method:

1. Update to the latest MacPorts version. Go grab a coffee because this will take up quite some time.
$ sudo port –v selfupdate
$ sudo port –v install postgresql92-server

2. Create the initial database for Music Cabinet:
$ sudo mkdir –p /opt/local/var/db/postgresql92/musiccabinet
$ sudo chown postgres:postgres /opt/local/var/db
$ sudo su postgres –c ‘/opt/local/lib/postgresql92/bin/initdb –D /opt/local/var/db/postgresql92/musiccabinet

3. To run the server manually:
$ sudo su postgres -c '/opt/local/lib/postgresql92/bin/postgres -D /opt/local/var/db/postgresql92/musiccabinet'

NOTE: The default user created is ‘postgres’ with the same password ‘postgres’.


How to increase Postgre maximum connection number?
NOTE: Proceed only if you see any FATAL ERROR: too many clients already in the terminal.

If you wish to increase the maximum connection number of Postgre from the default value of 20 to a higher number, the SHMMAX read by the kernel need to be increased as well.

You can check the current SHMMAX value by your running kernel by issuing
$ sysctl –a

and then you will find the following which is the default.
kern.sysv.shmmax: 4194304

To increase this value, you will need to create a file under /etc/sysctl.conf and enter the following lines as recommended by Postgre README file for MBP 2GB RAM. The purpose of creating the file is so that the changes made will be persistent each time you reboot the system.
$ nano /etc/sysctl.conf


How to Set Java Path to Java 7
1. Go to /Applications/Utilities and select Java Preferences.
2. Drag and drop Java SE 7 so that it is located at the top.

By doing so, your system is now configured to use JRE 7 as its priority and will only fallback if the Java application doesn’t support it.

3. In the terminal, type
/usr/libexec/java_home --version 1.7

4. This should return with a path such as

5. To include this as the $JAVA_PATH:
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_09.jdk/Contents/Home

NOTE: Using the following command would not register JAVA 7 because the latest Java 7 is not distributed by Apple, instead it is by Oracle.
export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

How to integrate PHP-CGI and Tomcat 6

1. Download php-cgi from MacPorts.
sudo port install php5 +fastcgi fcgi php5-gd php5-mysql php5-sqlite php5-curl php5-iconv

2. Add the following lines into /TOMCAT_DIR/conf/web.xml.
PhpJavaServlet php.java.servlet.PhpJavaServlet PhpCGIServlet php.java.servlet.PhpCGIServlet prefer_system_php_execOn php_include_javaOn PhpJavaServlet *.phpjavabridge PhpCGIServlet *.php
3. Follow the instructions here.

4. After extracting the files, put both JavaBridge.jar and php-servlet.jar into /TOMCAT_DIR/lib

5. Open context.xml found under the /TOMCAT_DIR/conf/

6. Append the following line to the Context header.
reloadable="true" privileged="true"

For example:
<Context reloadable="true" privileged="true">

<!-- Default set of monitored resources -->
<!-- Uncomment this to disable session persistence across Tomcat restarts -->
<Manager pathname="" />

<!-- Uncomment this to enable Comet connection tacking (provides events
on session expiration as well as webapp lifecycle) -->
<Valve className="org.apache.catalina.valves.CometConnectionManagerValve" />



1. Where is the Subsonic log file?
A. It is located under /var/subsonic.

2. Where is Tomcat Log file?
A. It can be found under /tomcat dir/logs. It is very useful to troubleshoot why a page refuses to load.

3. How to increase Tomcat heap size to prevent OutOfMemory error?
Type the following command in the terminal.
export JAVA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=512m"

Additional Setup

1. Subsonic Registration Engine - http://www.schattorie.com/subsonic-registration-engine/
2. Hiding server status and usage to public user - http://forum.subsonic.org/forum/viewtopic.php?f=3&t=8040&p=36224&hilit=hide#p36224

A. Subsonic Registration Engine

1. Follow the instruction here.

2. Extract and put the file into /TOMCAT_DIR/webapps.

3. Make some necessary changes to the following files:
- register.php

Change the domain name into your subsonic address.

- /lib/config.php
- /lib/mailconf.php

- /lib/mail/passresetmail.txt
Contains the format of the mail received by the user when they reset their password.

- /lib/mail/regmail.txt
Contains the format of the mail received by the user when they register.

Add the following to login.jsp so that it will display both the register and forgot password link.

<td align="left"><br><a href="http://musicscrape.zapto.org:8080/register/register.php" >Register</a>
<br><a href="http://musicscrape.zapto.org:8080/register/forgotpass.php">Forgot password</a></td>



  1. Installing PostgreSQL9.2 on OS X Mountain Lion - http://phlippers.net/blog/2012/08/03/install-postgresql-9-dot-2-on-os-x-mountain-lion/
  2. Postgres Max Connections and Shared Buffers - http://gabe.grayum.name/?p=postgres_max_connections_and_shared_buffers
  3. FATAL: could not created shared memory segment - http://grokbase.com/t/postgresql/pgsql-general/12a76zj50s/mac-os-x-mountain-lion-fatal-could-not-create-shared-memory-segment-cannot-allocate-memory
  4. Installing TomCat 7.0.x on OS X - http://wolfpaulus.com/journal/mac/tomcat7
  5. Setting JAVA_HOME on Mac OS X 10.5 - http://www.mehtanirav.com/2008/09/02/setting-java_home-on-mac-os-x-105/
  6. Installing Java 7 on Mac OS X - http://www.vineetmanohar.com/2011/03/installing-java-7-on-mac-os-x/
  7. MusicCabinet - http://dilerium.se/musiccabinet/#installation
  8. http://www.helloyi.cn/index.php/2011/09/30/mac-osx-lion-macport-nginx-php/
  9. Serve PHP with Tomcat - http://www.thomasknierim.com/140/java/serve-php-with-tomcat/

musicScrape - Yet Another Music Streaming Service

Just to kill some free time in the past two days, I had decided to play with a new toy, this time it is yet another music streaming service simply name musicScrape. The sole purpose is to enable music streaming by genre (or called radio) and enable easy on-the-go streaming experience. Streaming can be done using HTML5 or any other external player.

This service is provided so that I can listen to music anywhere in the campus, but due to the usage of IPv6 I had decided to allow access to the public too. Don't abuse it.

Visit the site at http://musicscrape.zapto.org:8080.