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 firstname.lastname@example.org and I will help you verrrrrrrrry fast.