## # filename: INSTALL (part of CouchMan - music playing and management system) # # Installation Documentation # # Copyright 2009 Pete Nesbitt (pete@linux1.ca) # # This file is part of CouchMan. # # CouchMan is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # CouchMan is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with CouchMan; if not, write to the Free Software Foundation, # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ## CouchMan is a music management and playback system. It uses a Browser based UI. It was designed as a standalone music server, but can be used as a local system application. System Requirements: -an x86 or x86_64 system running Linux -Apache (should work with any web server with some tweaks) -MySQL (should work with any DB but written to use mysql commands) -PulseAudio Note: all above requirements are included as part of most current Linuix distributuions. Tested (as server and client): -pico-itx x86, AMD 1GHz, 1 GB ram, Fedora 9 (pico image: http://www.linux1.ca/pics/Tech_Pico-ITX/medium/100_0948.jpg ) -x86_64, AMD Athlon 64 Processor 3200+, 1 GB ram, Fedora 9 (64 bit) -x86 Compaq P3, 384 MG ram. Test Results: -All systems performed well for both local and remote sound source except the Compaq which could not stay in sync when running as a networked client. -All remote sytems failed when serving RTP over Wireless (802.11g) Packages Needed: -Some of the Pulse & Alsa may not be required, but they are on my system alsa-lib alsa-plugins-pulseaudio alsa-utils httpd mplayer mysql mysql-libs mysql-server pulseaudio pulseaudio-core-libs pulseaudio-libs pulseaudio-libs-zeroconf pulseaudio-module-zeroconf pulseaudio-utils Note: In the following Detailed Server Setup, I refer to user: "musicman" and password: "musicman". You can use any user or passowrd you like but will need to remember to change the httpd.conf (if using patch method) and the htaccess password file (use htaccess command). No auto install program is available at this time. Hopfully later:) Detailed Server Setup: 1) unpack tarball (into /usr/local/src or wherever) 2) Become root "su -" 3) Create User and set Permissions: useradd musicman, passwd ownes cgi & html 4) Apache: Do one of: 1) Use provided Patch File: (httpd_patch in install_files directory) -this was created using Apache 2.2.9 (Fedora httpd-2.2.9-1.fc9.i386) cd /etc/httpd/conf cp httpd.conf httpd.conf_cm-orig cp [path/to/couchman-src]/install_files/httpd_patch . patch -c httpd.conf httpd_patch OR 2) Manually edit Apache config: -set httpd to run as user/group musicman/musicman -allow htaccess control of cgi dir (/var/www/cgi-bin) 5) Apache htaccess setup: This is recommended but optional if you want to restrict access to the Admin area. mkdir /var/www/passwords/ cp [path/to/couchman-src]/install_files/password.file /var/www/passwords/ chown -R musicman:musicman /var/www/passwords chmod 755 /var/www/passwords chmod 644 /var/www/passwords/password.file 6) Copy cgi and web pages 6a) cp [path/to/couchman-src]/cgi-bin/* [path/to/webserver]/cgi-bin/ eg: cp /usr/local/src/couchman.rc1/cgi-bin/* /var/www/cgi-bin/ -the .htaccess file is not copied, so also run: cp [path/to/couchman-src]/cgi-bin/.htaccess [path/to/webserver]/cgi-bin/ 6b) cp -r [path/to/couchman-src]/html/ [path/to/webserver/docroot]/ eg: cp -r /usr/local/src/couchman.rc1/html/* /var/www/html/ 7) Restart Apache run: service httpd restart -if it fails on the STOP line, that is fine, it was not already running. 8) Set up MySQL 8a) start mysqld run: service mysqld status if it is stopped, run: service mysqld start 8b) mysqladmin create db 8c) mysql grant rights: Do one of: 1) mysql -D cm_web_db < [path/to/couchman-src]/install_files/grant_string.txt OR 2) Manually set rights using: grant all privileges on cm_web_db.* to 'cm_user'@'localhost' identified by 'musicman' with grant option; flush privileges; 8d) mysql -create table Do one of: 1) Use provided SQL input File: ( newdb_table_string.txt in install_files directory) run (adjust as needed): mysql -u cm_user -pmusicman -D cm_web_db < [path/to/couchman-src]/install_files/newdb_table_string.txt OR 2) Manually create the table using this string: create table music ( id MEDIUMINT NOT NULL AUTO_INCREMENT, Artist VARCHAR(80), Genre VARCHAR(20), Album VARCHAR(80), Year VARCHAR(4), Track VARCHAR(80), Format VARCHAR(4), FullPath VARCHAR(450), PRIMARY KEY (id) ); 9) PulseAudio: (this is mostly used for standalone server) 9a) Modify the Pulse Audio Environment for Server Setup: - All the files we need to modify are in /etc/pulse 1) back up your pulse directory then go there cd /etc && cp -a pulse pulse_orig && cd pulse 2) client.conf -this file should be basically empty except we want to mess with the cookie location. The cookie line should be set to: cookie-file = /var/run/pulse/.pulse-cookie I also adjusted the idle time, but it probably is not necessary extra-arguments = --log-target=syslog --exit-idle-time=120 3) daemon.conf -this controls the daemon aspect To run as a system wide daemon, such as an appliance, change the following two lines: Change (or add as they are commented out, showing defaults) This: ; daemonize = no To: daemonize = yes Change (or add as they are commented out, showing defaults) This: ; system-instance = no To: system-instance = yes Optionally adjust this line to match your soundcard specs: ; default-sample-rate = 44100 I set mine to: default-sample-rate = 48000 4) default.pa -this is the main config file This is a tough one because I had to extract info from the pulse log (writes to messages) to determine the sound card string. There may/must be a better method, but here goes: My default.pa file, with comments and blank lines removed, looks like this: .nofail load-sample-lazy pulse-hotplug /usr/share/sounds/startup3.wav .fail .ifexists module-hal-detect.so load-module module-hal-detect .else load-module module-detect .endif .ifexists module-esound-protocol-unix.so load-module module-esound-protocol-unix .endif load-module module-native-protocol-unix load-module module-zeroconf-publish load-module module-rtp-send source=alsa_output.pci_1106_3288_sound_card_0_alsa_playback_0.monitor set-default-sink alsa_output.pci_1106_3288_sound_card_0_alsa_playback_0 load-module module-volume-restore load-module module-default-device-restore load-module module-rescue-streams I found the source=alsa_output.pci.. in /var/log/messages after starting PA. The following should show a similar string on your system: grep alsa_output.pci /var/log/messages* returns lots, including this (was all one line): sink.c: Created sink 0 "alsa_output.pci_1106_3288_sound_card_0_alsa_playback_0" with sample spec "s16le 2ch 48000Hz" 5) To run as a system daemon, create a symlink using this command: ln -s /etc/pulse/default.pa /etc/pulse/system.pa 9b) Set PA daemon to auto start via /etc/rc.local add this line to bottom of file: /usr/bin/pulseaudio (adjust path as needed, use 'which pulseaudio' to locate it.) 9c) Set PA daemon user to allow r/w to audio devices run: setfacl -m u:pulse:rw /dev/snd/* /dev/dsp /dev/audio /dev/mixer -on my system this fails on reboot. Just puting it in /etc/rc.local _before_ the pulse daemon until I figure it out. 9d) Get rid of PA log messages about wrong home: chmod -d /var/run/pulse pulse 9e) One problem I am still working on is that the cookie needs to be shared with the local musicman user (when starting mplayer) but it changes periodically and becomes perms of 600 (may be a timeing thing or may be on reboots during testing). The cookie requirement will be removed if I use TCP but that is not ready yet. We can set the cookie. Meanwhile, we can set the perms and make it immutable, it's overkill but will do for now. You must _first_ create a symlink musicman (or any other local users) as this cannot be done after teh file is 'locked down'. run: -the first two steps start/stop the daemon, creating the cookie pulseaudio kill -s SIGINT `pidof pulseaudio` rm -f ~musicman/.pulse-cookie ln -s /var/run/pulse/.pulse-cookie ~musicman/.pulse-cookie chmod 444 /var/run/pulse/.pulse-cookie chattr +i /var/run/pulse/.pulse-cookie If you need to create a link afterwords, or want to change the file, just run: chattr -i /var/run/pulse/.pulse-cookie 9f) At this point you can copy the pulse cookie to any machines you would like to play the music stream. On the remote machine place it in the users home or if also running as a daemon, then in /var/run/pulse. scp /var/run/pulse/.pulse-cookie @//.pulse-cookie eg: scp /var/run/pulse/.pulse-cookie pete@cosmo/home/pete/ -scp will overwrite the remote file if it exists 9g) The remote system must be told to listen to the RTP stream. On the remote system receiving the stream, edit /etc/pulse/default.pa and change (or add) this line: # load-module module-rtp-recv To: load-module module-rtp-recv No other changes, other than steps 9f & 9g are required on remote Linux systems. There are supposed to be PulseAudio clients for Mac and Windows but I am not familiar with those OS's. 9h) Restart PulseAudio, kill first if already running run these two lines: if [ `pidof pulseaudio` ]; then kill -s SIGINT `pidof pulseaudio`;fi source /etc/rc.local 10) Set the required services to start on bootup. chkconfig mysqld on chkconfig httpd on Note, that Fedora has been setting the 'network' service to _not_ start at boot, relying on 'NetworkManager' to maintain things. This is probably 'okay' for DHCP based environments, it can break your box if you do a network install using dhcp, then configure it statically in the install. Your settings are overwritten by Network Manager that uses the dhcp info from the install. In most cases that lease will not renew and the box will be off the network. If you don't like that and want more control over your network, do this: chkconfig NetworkManager off chkconfig network on That should do it for the install. NEXT STEP: Read the POPULATE_DB for instructions on inventorying your music. # EOF