$CVSHeader: ampache/INSTALL,v 1.12 2004/03/23 08:28:50 vollmerk Exp $

INSTALL - Ampache v.3.1 - 11/23/2003

  I'm assuming that you have Apache, PHP and MySQL running when you
  get to this point.

  If you're upgrading from 3.0 to 3.1 please refer to the MIGRATION Notes.
  Your database can't be re-used, but fear not the Ampache guys thoughtfully 
  included scripts to port the data from your old database to the new one.  
  (They get an extra beer for that one)
    
  1. Quick Install:

  mysql -u <username> -p <database name> < $yourroot/ampache/sql/ampache.sql

  edit /etc/apache/httpd.conf:
  point the webroot at $yourroot/ampache/docs/
  Restart Apache

  move $yourroot/ampache/modules/ampache.cfg.dist to 
  	$yourroot/ampache/modules/ampache.cfg
  edit $yourroot/ampache/modules/ampache.cfg for your site
  Go to $web_url/login.php and login with the following 
  	Username: admin
	Password: changeme

  2. The Long of it Setting Up Ampache

    2.1 Configuring Apache Server
    There are really two choices here.  You can either configure a virtual
    server for the ampache services, or you can just configure a new directory
    directive for ampache.  There are advantages and disadvantages for both.

    If you configure a new virtual server, it has it's own log files which
    could be useful for separating the ampache web traffic from the regular
    web server traffic.

    If you configure a new directory directive for ampache, the ampache
    statistics will be in with all the other web traffic, but it may be a
    little easier (but not by much).

    We've included cronolog lines. These are not required, but for 
    troubleshooting we recommend them. 

    for a separate virtual server httpd.conf reads:

    [snip]

        <VirtualHost 192.168.100.2:80>
           ServerName tunes.ampache.org

           ServerAdmin webmaster@ampache.org
           DocumentRoot /data/www/ampache/docs

           DirectoryIndex index.php

           ErrorLog "|/usr/sbin/cronolog /data/www/tunes/logs/error/%Y%m%d.log"
           TransferLog "|/usr/sbin/cronolog /data/www/tunes/logs/transfer/%Y%m%d.log"
        </VirtualHost>

    [snip]

    Now perform an 'apache restart' and apache should be configured.

    2.2 Configuring Your MySQL Server
    Setup a user and pass for your music db.

    Run: 'mysql -u user -p pass < sql/ampache.sql'
      to create the music db and tables.

    2.3 Configuring Ampache

     2.3.1 Configuring ampache.cfg
   
        Open up modules/ampache.cfg and edit a few variables:

        # Database Server hostname
        local_host = localhost

        # Database name
        local_db = ampache

        # Database username
        local_username = <mysql_login_name>

        # Database password
        local_pass = <password>

        # Login Length in seconds for local logins
        local_length = 900

        # This is the DOMAIN for the cookie that stores your session key
        # this must be set to the domain of your host or you will not be
        # able to log in make sure you including the leading .
	# Not required
        #sess_domain             = .http://www.ampache.org

        # Name of the Session/Cookie that will sent to the browser
        sess_name               = ampache

        # Lifetime of the Cookie, 0 == Forever (until browser close) , 
        # otherwise in terms of seconds
        sess_cookielife         = 0

        # Is the cookie a "secure" cookie?
        sess_cookiesecure       = 0

	prefix = "/<ampache_root>" 
	web_path = "http://<yourdomain>" 
	site_title = "Ampache!!!" 

	# Skinny of it, leave this off massive performance bonus 
	do_mp3_md5 = "FALSE" 

	# The interval at which it echo's our current progress on your 
	# catalog build, for large catalogs we recommend you increase 
	# this number 
	catalog_echo_count = "25" 

	# This sets which ID3 tag takes precedence. 
	# we've found for those of you who don't have 
	# good v2 tags it's sometimes nice to keep the v1 
	# until you've fixed v2 
	id3tag_order = "id3v2" 
	id3tag_order = "id31v" 

	# Un comment if don't want ampache to follow symlinks 
	#no_symlinks = "true" 

	# Use auth? 
	use_auth = "yes" 

	# Artist & Album Cache Limit 
	# In order to speed up catalog builds, and reduce the load on mysq we 
	# cache name --> id to save mysql lookups... You are welcome to comment 
	# this out to change it, or change it to your liking... 
	album_cache_limit = "25" 
	artist_cache_limit = "50" 

  3. Running Ampache For The First Time

        Point your browser at your new ampache webpage and you should get 
        the login prompt.  The first time login should be:
                user: admin
                password: changeme

        Grab A Beer....

      3.1  Setting up a catalog
        First, create your local catalogs.  Do this my first clicking
        `Add a catalog', and entering the path for the root of your
        collection of MP3 files.  There is no need to enter sub directories
	since the update tool will recursively catalog all subdirectories.

        You can enter multiple paths, so this means that you can access
        multiple directories, and hence multiple hard disks.  I solved this
        particular problem by patching the kernel to include logical volume
        management, but that's a completely different story.
	
      3.2  Updating your Catalog
        If everything went correctly, you are now looking at an empty ampache.
        In order to populate the database with all the tag information from
        your MP3 files, you'll need to go to the `Admin' page, and select
        the `Catalog' link.

        Finally, you want to click the `Update All Catalogs' button in the
        middle of the Catalog page and go for coffee (or any other beverages
        you like) as this will take a little bit of time.  The web server
        is now searching for and opening each of the MP3 files in your
        collection, pulling the ID3 tag data out, and using these to populate
        your ampache database.

        Final Note on MP3 Tags:
        Since you the value of ampache is directly related to the data in the
        database, and this data is obtained from the ID3 tags in your MP3 files,
        it really pays to have all your tags populated and in order.

        One of the best tools that I've run across to do this is:
        EasyTAG - Tag editor for MP3 and OGG files
        http://easytag.sourceforge.net

        It runs right on the Linux machine, and is quite a bit faster at updating
        tags than any PC based programs that have to access the MP3 across a
        Samba share point.  But this does not mean that you can't update tags
        this way.  Just that the local Linux program can access the MP3 faster.

        If you insist on using a windows version another good tool can also be 
        found on sourceforge at: http://massid3lib.sourceforge.net/
    
      3.3  Adding Users
	To Add Users simply click admin->users->Add a new user and enter
	the appropriate information


      3.4  Sorting and updating files (Under Development)
        When updating catalog preferences new fields added in v3.1 include
           ID3 set command
	   Filename pattern
	   Sort Pattern

	When these fields are populated a periodic update may be performed by scheduling
	the fileupdate.pl program to run at timed intervals.  This program will query the 
	database and attempt any requested updates. Before fileupdate.pl can be run, the 
	Ampache.pm file must be edited to reflect your archive information.
	
	Usage of fileupdate.pl is as follows:

	    fileupdate [--id3|--rename|--sort|--all] [--help] [--pretend] [--verbose]
              --pretend   Display command taken, without actually doing anything.
              --id3       Update id3 tags for all files flagged with 'id3'
              --rename    Rename files flagged with 'rename'
              --sort      Sort files flagged with 'sort'
              --all       Performs id3 update, rename, and sort
                          for all files flagged with 'id3'
              --verbose   Shows detailed information about what's happening.
              --help   This message

	
	
	An example usage would be to schedule a cron tab which will run fileupdate.pl with 
	the appropriate arguments which runs every 6 hours.

	EXAMPLE:
        If you were to place the following line in your crontab:
	     * 24 * * * /apache/bin/fileupdate.pl -all

	any updates applied to the database would be applied at midnight everyday


