[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/


Keep it up! I have learnt alot throughout ur blog.


Greetings! This is my 1st comment here so I just wanted to give a quick shout out and say I really enjoy reading your
posts. Can you recommend any other blogs/websites/forums that go over
the same topics? Thank you!
Feel free to surf my blog post :: backup camera


Thanks for sharing this guide! I can use this as my reference. Will try to do it this weekend.


Hiv disease for the last 3 years and had pain hard to eat and cough are nightmares,especially the first year At this stage, the immune system is severely weakened, and the risk of contracting opportunistic infections is much greater. However, not everyone with HIV will go on to develop AIDS. The earlier you receive treatment, the better your outcome will be.I started taking ARV to avoid early death but I had faith in God that i would be healed someday.As a Hiv patent we are advise to be taking antiretroviral treatments to reduce our chance of transmitting the virus to others , few weeks ago i came on search on the internet if i could get any information on Hiv treatment with herbal medicine, on my search i saw a testimony of someone who has been healed from Hiv her name was Achima Abelard and other Herpes Virus patent Tasha Moore also giving testimony about this same man,Called Dr Itua Herbal Center.I was moved by the testimony and i contacted him by his Email.drituaherbalcenter@gmail.com We chatted and he send me a bottle of herbal medicine I drank it as he instructed me to.After drinking it he ask me to go for a test that how i ended my suffering life of Hiv patent,I'm cured and free of Arv Pills.I'm forever grateful to him Drituaherbalcenter.Here his contact Number +2348149277967...He assure me he can cure the following disease..Hiv,Cancer,Herpes Virus,Epilepsy, fibromyalgia ,ALS,Hepatitis,Copd,Parkinson disease.Diabetes,Fibroid...


Post a Comment

If you found this article or post helpful to you, feel free to enter your comments below ;)