Location: PHPKode > projects > Musichearts > musichearts-0.2.2/INSTALL.TXT
MUSICHEARTS INSTALLATION GUIDE

1 Introduction
==============

Musichearts provides a downloadshop with nice functionality right 
inside your homepage. This means, you need a hosted webpage, 
because you will install musichearts into your own webpage. The 
webserver needs to provide php5.

Basically there a 2 types of installation. 

- Stand alone installation, by just linking to the webshop page 
  from somewhere in your existing homepage. The musichearts link 
  creator provides you with working link code to have nice popups 
  for selling your music.

- Embedded installation, where only the <body> main part of 
  musicheads is included into an existing page.

Install method 1 is the one which requires less work and 
knowledge and therefore is recommended for newbies.

Install method 2 is the better styled one which integrates 
seamlessly into the existing page. Anyhow this way requires more 
knowledge of how to handle websites from the technical point of 
view.

Anyhow you should definetely run the test in install checker 
(chapter 3.1) after having done the 
setup. It checks for most common errors and tells you about them.

And no worries, no one will be able to shop or download songs 
until you finished the installation. Go live has to be set 
explicitly by you.

Final remark before we start: In paypal you will be able to 
download an abstract of account which will show you when you sold 
which songs.



2 Installation 
==============

It is VERY IMPORTANT, that you carefully follow ALL of the steps 
in this installation instruction. Please do not skip any step if 
you have problems. You may have the impression that things still 
work, but bad effects may occur. People may even send you payment 
but not be able to receive any song or be able to download the 
songs for free. If you have problems installing feel free to 
contact 'info[at]musichearts.org', you will be helped quite 
quickly. Since musichearts a is pretty new software, made with 
passsion, please support me and do only run complete 
installations.

2.1 Common installation (for all installation kinds)
----------------------------------------------------

2.1.1 Copy musichearts onto your webserver

It is recommened to use a sub directory of you website root. 
(e.g. www.mysite.com/musichearts)


2.1.2 Enter your artist data

To personalize your shop and give customers a possibility to 
contact you, please edit config.php and enter your band/artist 
name and your contact email address. Please note that you email 
adress will be spam protected and not displayed in cleartext.

The corresponding variables in config.php are as follows:

$musichearts_band_name  = '<your band name>'; 

$musichearts_band_email = '<your email address>';


2.1.3 Get a paypal account

Althought musichearts probably will work with any type of paypal 
account, it has been tested under business accounts. So 
recommended setup is a paypal business account (which costs no 
monthly fees).


2.1.4 Activate PDT in your paypal account.

Specifiy the URL of your musichearts installation as return URL. 
(e.g. www.mysite.com/musichearts) You have to tell paypal that 
after a transaction to forward back to your musichearts webshop 
and post the transaction data, so that the song download can be 
enabled. You will need your paypal authentification token for 
step 2.1.7.


2.1.5 Deactive IPN in your paypal account.

We just want to be sure, IPN settings cannot lead to a missing 
redirect to the direct download. Also musichearts does not 
support IPN, but probably will in future.


2.1.6 Secure 'db' and 'mp3' directory

To protect from unauthorized downloads, make sure that 'db' and 
'mp3' subdirectories cannot be read from external. Nevertheless 
those directories must be readable by webserver user. (If you are 
using apache, a correct .htaccess file is already included into 
musichearts)


2.1.7 Enter you paypal account and authentification token into 
  config.php

They have to be filled in as:

$musichearts_paypal_username

$musichearts_paypal_auth_token

People won't be able to read this from external.


2.1.8 Enter the price you want each song to cost (and change 
  currency if needed)

Just set in config.php: 

$musichearts_song_price = '<price>'; // e.g. '0.50'

Please mind that Paypal takes ~0.30 per transaction (EU/USA), no 
matter how many songs you sell (also if you sell 5 songs, it is 
still "only" ~0.30 PayPal fee). Some more info can be seen here 
for USA: 

https://www.paypal.com/cgi-bin/webscr?cmd=_display-fees-outside 

and here for Europe:

https://www.paypal.com/us/cgi-bin/webscr?cmd=_display-fees-outside&countries=EU 
(EU).

Check 

https://www.paypal.com/worldwide/

for information about supported currencies.

To adjust the currency being used in musichearts change variable 
as follows in config.php: 

$musichearts_song_currency = 'EUR'; // or 'USD' or whatever


2.1.9 Upload the songs you created

The songs you composed and sang, upload them to mp3 subdirectory


2.1.10 Create snippets for preview listening from your songs

The snippets have to be in 'mp3_preview' subdirectory. 

Filenames have to be as illustrated in this example:

mp3/song1.mp3 -> mp3_preview/song1.preview.mp3 

mp3/song2.mp3 -> mp3_preview/song2.preview.mp3

mp3/song3.mp3 -> mp3_preview/song3.preview.mp3

Tools like mhwaveedit or audacity can be used for this.


2.1.11 Open 'db' directory

Make sure the 'db' directory is writeable for the user, you 
webserver is running as (or for all users which would include him 
:P). This is needed so transactions can be written to database.


2.2 Standalone installation (additional tasks)
==============================================

NOTE: Only do 'Standalone installation' OR 'Plugin installation'.

2.2.1 Have a Shop Popoup in your page

Use a webbrowser to navigate to 

<directory_where_you_copied_musichearts_to>/tools/link_creator.php 

Copy/Paste the generated link into your homepage. That's it.


2.3 Plugin installation (additional tasks)
==========================================

NOTE: Only do 'Standalone installation' OR 'Plugin installation'.

NOTE: musichearts code is XHTML 1.0. For a complete validating 
and clean install, plugin installation should be done inside a 
XHTML 1.0 page. Probably XHTML 1.1 will work fine, too, but still 
has to be tested. Integration into HTML 4.01 will be pretty messy 
concerning validation and is not recommended although it might 
run - Standalone integartion is recommended here.

2.3.1 Change config file entry for plugin use

Change entry in config.php as follows:

$musichearts_complete_html_page = false; // set to true or false 
(no quotation)


2.3.2 Insert session code at top of page

Change '<directory_where_you_copied_musichearts_to>' with the 
actual directory. The trailing / is mandatory!

<?php 
  define( 'musichearts_root_dir', '<directory_where_you_copied_musichearts_to>/' ); 
  // NOTE: the trailing '/' is mandatory! 
  $musichearts_current_dir = getcwd();
  chdir( constant( 'musichearts_root_dir' ) ); 
  include 'include_inline.php'; 
  chdir( $musichearts_current_dir ); 
?>


2.3.3 Insert header code in header

<?php 
  chdir( constant( 'musichearts_root_dir' ) ); 
  include 'include_head.php'; 
  chdir( $musichearts_current_dir ); 
?>

2.3.4 Insert body code in body

<?php
  chdir( constant( 'musichearts_root_dir' ) );
  include 'index.php';
  chdir( $musichearts_current_dir );
?>


2.3.5 Complete example for inline code insertion

+ <?php 
+   define( 'musichearts_root_dir', '<directory_where_you_copied_musichearts_to>/' ); 
+   // NOTE: the trailing '/' is mandatory! 
+   $musichearts_current_dir = getcwd(); 
+   chdir( constant( 'musichearts_root_dir' ) ); 
+   include 'include_inline.php'; 
+   chdir( $musichearts_current_dir ); 
+ ?> 
<html>
  <head>
    ... other header content ... 
+   <?php 
+     chdir( constant( 'musichearts_root_dir' ) ); 
+     include 'include_head.php'; 
+     chdir( $musichearts_current_dir ); 
+   ?> 
  </head>
  <body> 
    ... body content before shop ... 
+   <?php + chdir( constant( 'musichearts_root_dir' ) ); 
+     include 'index.php'; 
+     chdir( $musichearts_current_dir ); 
+   ?>
    ... body content after shop ... 
  </body> 
</html>



3 Test
======

3.1 Run the install checker
------------------------------------------------

Open your webbrowser and navigate to 


<directory_where_you_copied_musichearts_to>/tools/install_checker.php

It will tell you about errors in you setup.


3.2 Test in PayPal Sandbox
--------------------------

Go to 

https://developer.paypal.com/

register a test account and test your shop. You have to edit 
config.php and set

$musichearts_development_mode = true

in order to be able to run this test. After this change all 
transactions will be send to paypal development test server. This 
is a perfect way for you to test everything is running fine.



4 Go live
=========

Edit config.php and set:

$musichearts_install_finished = true

You musichearts mp3 download shop is online now.



A Support
=========

Just contact hide@address.com and I will help you 
verrrrrrrrry fast.

Return current item: Musichearts