Multi-Server ColdFusion: Upgrading from MX 7 to ColdFusion 8

Very little has been written about how to upgrade your multi-server install of ColdFusion MX 7 to multi-server ColdFusion 8. Not even Adobe will tell you how to do it. Fear not, because I'll give you step-by-step instructions to get it done.

We have been running multi-server CF7 on JRun for the past year or so and have just completed the upgrade to CF8. We typically run about 10 instances of ColdFusion on a server, so the goal of the upgrade was to move to CF8 without impacting the sites that were already comfortably running on CF7.

I will assume you are using:

• ColdFusion MX 7.02 multi-server
• JRun4 as your J2EE platform
• Windows 200X Server

This should work for other operating systems, but you will have to figure out the particulars for yourself.

General Overview of the Upgrade Process:

• Backup server
• Download necessary files from Adobe
• Backup CF instances using CF Archive files (.car)
• Remove all CF instances
• Backup major file centers (optional)
• Uninstall ColdFusion MX 7
• Install ColdFusion 8 (multi-server)
• Install CF8 Hotfix (optional)
• Restore CF Instances
• Connect CF Instances to their Web Sites
• IIS Settings - Default Doc, CFIDE mapping
• Re-install Custom Tags

Here are the full step by step instructions:

Step 1: Backup and Preparation

Purpose: Disaster Recovery. We use VMWare server virtualization, so this step is as simple as making an "image" of our server.

1. Backup your server using whatever methods are available to you.
2. Download the following files from Adobe and put them into an easily accessible directory on your server, such as: C:\CF8Upgrade You will want this path to be short because you will have to either type it or browse to it a number of times.
3. Coldfusion-8-win.exe - When you download from Adobe, there are 2 options, Developer Edition and Trial Edition. These are the exact same files. Also, these files are actually the complete, full install of CF8. The full features 30-day timer is disabled by entering your serial number.
4. CF8 cumulative Hotfix - This is optional as per Adobe instructions. **NOTE** Updater 8.01 has been released, but we have not yet installed it, so we can't help you there.

Step 2: Backup Existing CF Instance Settings

Purpose: To avoid losing your ColdFusion Admin settings for all of your existing sites.

• Log into CF7 Master CFAdmin > Enterprise Manager > Instance Manager. Make sure all instances are running.
• Take a screen shot of Enterprise Manager > Instance Manager for use during CF8 instance re-build. This is so you can rememeber the exact names of your instances. Stick the image in "C:\CF8 Upgrade\backups\" so you can refer to it when re-creating instances.
• Proceed through each instance and make create a setting backup .car file
  • Starting at the top, click on the icon to access that instance's CFAdmin. (the rightmost icon)
  • In the new CFAdmin > Packaging & Deployment > ColdFusion Archives (.car)
  • Create New Archive > provide a name (example: XYZCompanyBackup)
    • If you receive a "500" error here, see below for a solution, and then continue here!
  • A new window opens > Click "Select All" > Close Window
  • Now click on the center icon (Build Archive) next to your newly created Archive in your instance CFAdmin
  • A new windows opens > Click "Next"
  • Choose a physical location for your .car file.
    • "C:\CF8 Upgrade\backups\XYZCompanyBackupBackup.car" - You must include the .car extension!
    • TIP: Copy this so you can paste it for the next round... just editing the file name.
  • Click "Next"
  • Should receive alert message "Build Successful"
  • Click "OK" > Close window
  • Close that instances CFAdmin browser window completely
  • Back in the Master CF Admin Instances > STOP the instance you just backed up. This is mostly used to keep track of which instances you have already backed up.
  • Proceed to the next instance and repeat.

Step 2(Java 500 Error): I got a Java "500" error when I tried to create a ColdFusion Archive!

Reason: At some point in your ColdFusion installation history, you probably told ColdFusion to use a different version of the Java Runtime Environment than the one that comes with CF. No problem. This is easily fixed. Here are my notes on the subject.

• STOP ALL CF JRun INSTANCES BEFORE DOING THE FOLLOWING!
• Open file: D:\JRun4\bin\jvm.config (may be in a different location for you)
• Change the "java.home" line to this "java.home=D:/JRun4" (direction of slash is critical). Why? This will force JRun to look for a JRE as per the documentation in the file. It should find and use the JRE that comes installed with JRun... and therefore should not through errors in the CFAdmin. You might ask "Why was this value changed in the first place?" Good question. You might have changed it in order to deploy other J2EE apps which required JRun to run a newer version of the default installed JVM. That was our situation.
• Save jvm.config file
• Restart JRun Admin service
  • Close your browser with the Master CFAdmin in it.
  • Windows Services > Stop and Start "Macromedia JRun Admin Server" and "Macromedia JRun Cfusion Server"
• Re-try creating .car file as above.
  • When you re-enter the Master CFAdmin, you may find the archive already "created". Just click on the left-most icon (Edit Archive Definition) to re-try creating the archive.

Step 3: Remove all existing CF Instances via the Master CFAdmin

Purpose: To remove existing instances from CF7 and as Windows Services

• Log into the Master CFAdmin
  • Enterprise Manager > Instance Manager
  • Stop and delete each instance
• Close your web browser
• Don't reboot now, you will be doing so in the next step

Step 4: Backup Major File Centers (generally optional)

Purpose: Disaster recovery. Though damage to these areas is highly unlikely.

• Shut down all CF services using the Windows Services Tool
  • All CF Instances including "Admin" and "Cfusion".
  • ColdFusion MX 7 ODBC Agent
  • ColdFusion MX 7 ODBC Server
  • ColdFusion MX 7 Search Server
  • Any other deployed J2EE apps that use JRun
• Copy your web root (D:\Inetpub) to C:\CF8 Upgrade\backups
• Copy D:\JRun4 to C:\CF8 Upgrade\backups

Step 5: Uninstall ColdFusion MX 7

Purpose: To remove CF MX 7 and its related Windows Services

• Use Add/Remove Programs to uninstall
  • Wait for entry in Add/Remove Programs to disappear (it can take a minute or two)
• Restart computer
• Upon restart, clean up remnants
  • Delete icons from Desktop
  • Delete entries from Start Menu
  • Delete JRun4 directories from both C: and D:
• Check that all relevant services are gone, etc.
  • Other deployed J2EE apps (if any) running as services should still exist

Step 6: Install ColdFusion 8

Purpose: To keep rockin in the ColdFusion world.

• Run Coldfusion-8-win.exe and follow install wizard
  • Enter Serial Number for CF8
  • Enter Serial Number for CF7
  • Next Screen > Select "MultiServer" edition
  • Next Screen > Select only the first two options (your needs may vary)
  • Next Screen > Specify "D:\JRun4" for JRun installation (may be different for you)
  • Next Screen > Select "All IIS Websites" (may be different for you)
  • Select "D:\Inetpub\wwwroot" for CF Admin location (may be different for you)
  • Next Screen > Specify Admin Password
  • Next Screen > Enable RDS (for non-production only)
  • Next Screen > Click "Install" and wait. Got get some coffee, you deserve it.

Your settings summary may look something like this:

• Continue following instructions
  • Click to open Master CFAdmin in default browser
  • Log in and wait
  • Click "OK" > Success!
• Create desktop icons for Master CFAdmin
  • Drag icons from Start Menu and name as follows
    • CF 8 Master Admin
    • JRun Admin (optional)
    • Web Server Configuration Tool
• Where is my "ColdFusion8" directory?
  • You may notice that no such directory exists
  • CF8 is installed as a deployed application under JRun

Step 7: Install Hotfixes if Desired

Purpose: To secure your CF8 installation with the latest and greatest patches and fixes.

Now would be a good time to do that, if desired. This is recommended. Download them and install them as per Adobe instructions. Typically, HotFixes are installed via the "System Information" button in the CFAdmin. That's the small little "info" button at the top right.

Step 8: Create CF Instances

Purpose: To get all of your clients back up and running. :)

• CF8 Master Admin > Enterprise Manager > Instance Manager
• Start adding all necessary instances
  • Refer to screen shot captured during backup phase OR refer to another server
• Click "Add New Instance"
  • Enter the correct Server Name in that field
  • Check "Create Windows Service"
  • Check "Auto Restart Service"
  • Click "Submit" and wait until you are told to wait no longer!
    • This can take longer than you might think.

Step 9: Restore CF Instance Settings

Purpose: To reset all of your instances with their original settings, datasources, mappings, etc.

• Log into the CFAdmin for a particular instance
  • Deploy an Existing Archive > Browse for .car file
  • Example: C:\CF8 Upgrade\backups\XYZCompanyBackup.car
  • Click "Deploy" > A new window opens
    • Click "Next"
    • Click "Deploy" and wait!
    • Should receive "Deploy Successful" alert
    • Click OK > Close
  • Check Mappings and Data Sources to verify settings were carried over properly

Step 10: Connect CF Instances to their websites

Purpose: To make sure that your webserver (in this case, IIS) knows how to talk to each ColdFusion instance.

• Open up the "Web Server Configuration Tool" using your desktop icon
• Click "Add"
• Select your JRun Server
  • Example: XYZCompany
• Select your IIS Website
  • Example: XYZCompany_Portal
• Click "Configure for ColdFusion 8"
• Click "OK"
• Click "Yes" to restart the web server

Step 11: IIS - Reset the Default Document

Purpose: To get IIS to server up index.cfm before index.html

Uninstalling CF 7 removes "index.cfm" from the default documents within each IIS website. Installing CF 8 adds it back in, but at the bottom of the list. Heck no.

• Visit each website in IIS and restore "index.cfm" to its rightful place above all other pitiful default documents!!!
  • IIS > Website> Properties > Documents

Step 12: IIS - Set up CFAdmin access (optional)

Purpose: If desired, you can virtually link the CFIDE to any of your websites for remote access to the instance CFAdmin. This is optional because some folks might want to simply RDC to their server and access the instance CFAdmins via the Master CFAdmin > Instance Manager

• In turn, click on each site that has been newly setup in IIS.
  • Right click > New > Virtual Directory
  • New Window > Next
  • Enter: "cfide" for the alias > Next
  • Browse for directory > "D:\Inetpub\wwwroot\CFIDE" > Next > Next > DONE!

Step 13: Re-deploy any J2EE Apps (optional)

Purpose: If you have any J2EE apps that need to run under specific instances within JRun, you will need to re-deploy them. We did. You can probably skip this step.

• Log into the JRun Administrator
• Click on instance name
• Click "Add" under "Web Applications"
• Browse to your J2EE application path
• • Click "Open"
• Click "Deploy"
• On next page, scroll down and click "Apply"
• Click link back to instance overview

Step 14: Re-install/Test Your Custom Tags

This process varies so much that I'll leave it for you to figure out for your particular application.

Step 15: Test Your Websites

Your sites and apps should all be working now as normal. To see your new CF version number in all it's glory, try running this code.

Have fun.