Upgrading Jamroom 2.x to Jamroom 3
Upgrading a Jamroom 2.x install to Jamroom 3 is a pretty straight forward process, however it is more involved and detailed than past Jamroom upgrades due to the new directory structure for the Jamroom templates. You will also need to edit some of your existing Jamroom templates to use in Jamroom 3, as some of the "default" values for Jamroom 2.x scripts no longer have a default meaning in the Jamroom 3 equivalent script.
Please make sure and CAREFULLY follow these upgrade directions in order - skipping any of the steps, or performing them out of order could result in your Jamroom being in a non-functioning state.
Upgrade Steps
 |
Please Read these steps carefully and completely BEFORE beginning your upgrade! Note that steps 1 - 5 can be fully completed BEFORE you do the actual script upgrade process. It is recommended that you spend extra time on these initial steps (especially step 4), as this is the most likely place to run into problems with the upgrade - an improperly converted/created Jamroom Skin. |
- 1. Verify your Server meets the Jamroom 3 Minimum Requirements
The first thing you want to do is to make a complete backup of your current Jamroom 2.x system - this is important - Jamroom 3 is very new, and while it has been tested thoroughly with upgrading Jamroom 2.x installs, with several thousand Jamroom 2.x installs it is impossible to test on every combination of OS, Web Server, MySQL and PHP version that is out there. Having a good backup will let you breathe easier, knowing if you get into a state where things are not working or going well, you can simply "back out" of the upgrade and revert to your previous Jamroom 2.x install. Some tools to help you create your backup:
phpMyAdmin - phpMyAdmin is highly recommended product to use on any site running MySQL/PHP - it is a very easy to use SQL front end for your MySQL server. You can "export" your Jamroom database from within phpMyAdmin, and later re-import it if you need to revert your database back to it's previous state.
A separate Backup Guide has been developed to help you with the steps needed to properly back up your Jamroom.
- 3. Modify Database Settings file with correct values
The next step, is to modify your jamroom/config/settings.cfg.php file with the correct values for your server. In Jamroom 2.x, there was support for a "detect" mode for the jamroom_path, jamroom_url, directory_mode and file_mode settings - this is NO LONGER supported in Jamroom 3. Jamroom now requires the proper values for these settings. You may need to contact your hosting provider for assistance with these settings, as it is very important that they are set correctly:
Change these settings from "detect":
$config['jamroom_path'] = 'detect';
$config['jamroom_url'] = 'detect';
$config['directory_mode'] = 'detect';
$config['file_mode'] = 'detect';
To the proper values for your server (these are just example entries - your values will be different):
$config['jamroom_path'] = '/home/yourname/public_html';
$config['jamroom_url'] = 'http://www.yoursite.com';
$config['directory_mode'] = 0777;
$config['file_mode'] = 0666;
Take special care in setting the "directory_mode" and "file_mode" settings - there can NOT be ANY quotes around the values! For example, the directory_mode setting would be 0777 - NOT '0777' or "0777" (if that was the proper setting for your server - same goes for the file_mode - no quotes!).
 One way to try and get the proper settings for your server is to log in to your Jamroom 2.x site as the Master Admin, then go to the Jamroom Tools -> Server Check option. Click on the "Click here for detailed PHP information" link next the PHP version in the output. Look in the "Server API" entry section near the top, which tells you the type of PHP install that is on your server. If it says "Apache", then your directory_mode should be set to 0777 and your file_mode should be set to 0666. If it says "CGI", or "fastcgi", or "fcgi" - basically anything with the letters "cgi" in it, you should set your directory_mode to 0755 and your file_mode to 0644. You can also scroll to the bottom of the output, and look for the "_SERVER["PATH_TRANSLATED"]" setting - this will typically show you the correct path to your Jamroom (just make sure you do NOT include the file name in the path setting!).
- 4. Acquire Jamroom 3 License
If you already have a valid Jamroom 3 license key, make sure and have it on hand as you will need it during the upgrade process to enter in to your Jamroom. If you do not have a valid Jamroom 3 license, you can purchase a new Jamroom 3 license, or a Jamroom 3 License upgrade (for previously registered Jamroom 2.x license holders) from the Jamroom Store. Please note that if you purchased your Jamroom AFTER 01/01/2006, the upgrade to Jamroom 3 is FREE. Please contact support@jamroom.net if you have not received your free Jamroom 3.x license.
- 5. Create Jamroom 3 "Skin" based on Jamroom 2.x "templates"
The next step, before upgrading, is to create a new Jamroom 3 "skin" based on your current Jamroom 2.x templates.
This step is likely to be the longest step of the upgrade process - there's no rush here though, as your site is still running Jamroom 2 - make sure and work through this stage carefully. The final results for your new "Skin" are completely dependent upon the care given at this stage to create your new Jamroom 3 Skin.
- Create a new directory in your Jamroom 2.x install called "skins". Within this directory, create a directory called "Jamroom_2". When you have created both directories, you should have a new directory in your Jamroom:
jamroom/skins/Jamroom_2
- Copy the contents of the following template directories into your new Jamroom_2 skin directory:
- jamroom/templates/index
- jamroom/templates/message
- jamroom/templates/calendar
- jamroom/templates/ranking
- jamroom/templates/newsearch
- jamroom/templates/newchart
- jamroom/templates/playlist
- jamroom/templates/rating
So that all of the template files end up inside the Jamroom_2 skin directory - i.e.
jamroom/skins/Jamroom_2/default_index.tpl
jamroom/skins/Jamroom_2/default_index.css
jamroom/skins/Jamroom_2/menu.tpl
... and so on ...
NOTE: If some of your templates have the same name as other templates, you will need to rename them! Make sure any URLs in your template files are updated to use the new name!
You should end up with the "default_index.tpl" file inside of the Jamroom_2 directory. (Please note - if your main Jamroom "index" page is NOT default_index.tpl that is OK - whatever you have named it, make sure ALL of the template files and sub directories are copied into the jamroom/skins/Jamroom_2 directory).
- Rename the "default_index.tpl" (or whatever template is the MAIN index template) to "jr_index.tpl" - this is required or Jamroom will NOT see the new Skin.
- Edit the templates in jamroom/skins/Jamroom_2, and look for any template "includes" that are referencing the former location of the templates - this would include URLs to images and CSS files as well - i.e.:
change:
{include file="$JAMROOM_DIR/templates/index/header.tpl"}
to
{include file="$SKIN_DIR/header.tpl"}
this:
<link rel="stylesheet" type="text/css" href="{$JAMROOM_URL}/templates/index/default_index.css">
would become:
<link rel="stylesheet" type="text/css" href="{$JAMROOM_URL}/skins/Jamroom_2/default_index.css">
and so on for each of the templates in the new Jamroom_2 skin directory.
The point of editing these files is to ensure that the templates are looking in the new Jamroom_2 skin directory, and no longer looking in the "old" template directory. It is HIGHLY recommended that while editing your "new" skin, you place a link to get to the Jamroom Control Panel somewhere in your menu, or other location. The URL to use is:
{$JAMROOM_URL}/index.php?mode=cp
- Update any URLs that point to "newchart.php" or "newsearch.php" - these scripts have been renamed in Jamroom 3 to "chart.php" and "search.php". Make sure any URLs in your templates (i.e. anchor tags) have been replaced with a call to the correct script.
- 6. Copy Artist Theme Templates to Theme Directories
In Jamroom 3, all of the different templates that can be used in an Artist/Member Theme, are now located within the theme directory itself. This includes contact, comment, guestbook, rating and playlist templates. Where previously in Jamroom 2 you would find these templates located in the jamroom/templates/<script_name> directories, these templates now need to be copied to the Artist/Member Theme directory that they belong to.
- 7. Upload the Jamroom 3 archive
Next, upload the entire Jamroom 3 archive contents allowing the new files to overwrite your existing Jamroom 2.x files.
- 8. Run the "upgrade.php" script
When the FTP upload of the Jamroom 3 files is complete, download the Jamroom3 Upgrade script, upload it to your Jamroom directory, and run the "upgrade.php" script from your browser:
http://www.yourdomain.com/jamroom/upgrade.php
Note that the upgrade process can take up to 2-3 minutes to run on a large system, so please do NOT interrupt the upgrade until it is complete, or your Jamroom will be left in an inoperable state.
- 9. Log in as Master Admin
After the upgrade is done, log in to your Jamroom as the Master Admin. Note that the upgrade sets your Default Skin to the new Jamroom 3 "Cobalt" skin to ensure a functioning template allowing the Master Admin to log in.
- 10. Run the "Jamroom Integrity Check" tool from the Jamroom Tools Menu
Next, make sure and run the Jamroom Integrity Check tool from the Jamroom Tools Menu - this ensures any extra database columns and indexes were upgraded correctly by the upgrade.php script.
- 11. Change the Jamroom Skin
Next, click on the Jamroom Config link in your upper left hand menu, and select the "Jamroom Skins" section. Click on the 'Set as Active Skin' button to the right of the "Jamroom_2" skin you have created. This will make the Jamroom_2 skin the "active" skin.
- 12. Enter your Jamroom 3 License
Next, click on the "register" link in the left hand menu, and enter your Jamroom 3 license registration (if registered). Jamroom 3 requires a NEW License Code - your Jamroom 2 License WILL NOT work with Jamroom 3!
- 13. Verify Jamroom Config Settings
Log in to Jamroom as the Master Admin, and go into EACH section of the Jamroom Config, verifying the settings are correct, and saving your settings. The are A LOT of new options in the Jamroom Config, and it is important that you "save" each section in the Jamroom Config to ensure the settings are changed from their default values.
- 14. Verify Jamroom Quota Settings
While still logged in as the master Admin, click on the "Browse Quotas" in the left hand menu. You will want to "Modify" each of your Jamroom Quotas and ensure they are set with the correct values for your Quotas. There are over 50 new options in the Artist Quotas alone, so make sure they get set correctly.
- 15. Verify Email Templates
Your next step is to verify the Jamroom E-Mail Templates. With Jamroom 3, all email templates are located in the jamroom/templates/email directory - verify that the templates contain the text and wording you would like for your system. You can do this by downloading all of the email templates in the jamroom/templates/email directory to your local computer, editing them, then re-uploading them via FTP. You will note that all of the new Jamroom 3 email templates begin with "jr_".
Potential Issues and Solutions
If you run into issues during your Jamroom Upgrade, the first thing is don't panic - double check that you followed the directions as listed above. Here are the solutions to some problems you may encounter after the Jamroom Upgrade:
- I'm receiving the Error "the template file does not exist or is not readable from the (directory) directory"
You will receive this error if Jamroom expects to find a template in a specific location, yet is unable to find that template in the proper location. The most common cause of this error is that you have NOT copied the template from the jamroom/templates/<directory> location in to your new jamroom/skins/Jamroom_2 directory, and Jamroom is expecting to find that template in the skin directory. Make sure you have copied all of the templates involved with your Jamroom site into your new jamroom/skins/Jamroom_2 directory.
- My Images are no longer showing after the upgrade to Jamroom 3.x
The most common cause for this error is that the directory_mode and file_mode settings in the jamroom/config/settings.cfg.php are NOT correct for your server, or there are "quotes" around the values. DO NOT use quotes around these values in your settings.cfg.php file - they should look something like this:
$config['directory_mode'] = 0777;
$config['file_mode'] = 0666;
NOT LIKE THIS:
$config['directory_mode'] = '0777';
$config['file_mode'] = '0666';
I would also recommend going into the Jamroom Config -> System Settings section, and adding your Domain Name to the "Deeplink Allowed Keywords" section if that still doesn't work.
- Jamroom 2.x Contact / Guestbook / Comment / Rating forms and templates do not work correctly after the upgrade
The first thing to check if your forms are not working correctly, is whether or not you have copied the templates into the Artist/Member theme directory. ALL templates that are used by Artist/Member themes should now be located in the actual theme directory (i.e. jamroom/themes/Cobalt) - not the jamroom/templates/<script_name> directory.
The second reason could be that you have configured Jamroom to require a User be logged in for the contact, guestbook, rating or comment forms - you can double check this from the Jamroom Config -> Account Settings -> Account Login Settings section. For Jamroom 3 to operate in Jamroom 2.x mode, ALL of the Login settings should be set to "no".
|
