===================================
Migrating to eduCommons $$version$$
===================================


Preparation
-----------
A few things you should do before beginning the migration:

1. VERY IMPORTANT: SAVE A BACKUP OF YOUR Data.fs FILE, which is located in the [old instance home]/var directory of your eduCommons site. This file contains all of the content for your site. (This way you will able to restore your file from this Data.fs file if anything goes wrong.)

2. Verify that your current instance is eduCommons-3.1.1-final.


Migration of eduCommons 3.1.1-final to $$version$$
--------------------------------------------------

The migration eduCommons from version 3.1.1-final to version $$version$$
includes the following:

1. Pre-migration of Data.fs in version 3.1.1-final

2. Movement of Data.fs file to a new $$version$$ instance

3. Migration to the eduCommons $$version$$ instance

4. Export/Import of eduCommons site to a new $$version$$ instance

5. Final steps

Pre-migration of Data.fs in version 3.1.1-final
-----------------------------------------------

For this step, you will need:

* contentmigration Plone Add-on Product, available at http://pypi.python.org/packages/source/P/Products.contentmigration/Products.contentmigration-1.1.zip 	 
 
* to copy the migration source code found in version 3.2.1.  The file is located at eduCommons/extras/PreMigrate.py

  * Copy this into [old instance]/Products/eduCommons/Extensions

Add contentmigration product by following these steps:

1. Download the product from the aforementioned pypi URL

2. Unzip the product. Products.contentmigration needs to be placed in the Products directory of your 3.1.1 instance. For example: /opt/Zope-2.10.6/edu311/Products. In addition, since it is currently only available as an egg, you will have to extract only the contentmigration directory into the aforementioned products dir. When you unzip the package from

http://pypi.python.org/packages/source/P/Products.contentmigration/Products.contentmigration-1.1.zip, it will look like a typical python egg:
  * Products.contentmigration-1.1
  * --Products
  * ----contentmigration

That is the actual 'Zope2 Product' that needs to be moved into your 3.1.1 Products directory.

3. Restart zope

Run the migration script by following these steps:

1. Open your 3.1.1-final eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)

2. From the drop down menu, select "External method" and click the Add button.

3. Enter the following parameters:

   * Id: PreMigrate
   * Title: PreMigrate
   * Module Name: PreMigrate
   * Function Name: pre_migrate_3_1_1_to_3_2_1

4. Click Add

5. Click on the PreMigrate script you just added

6. Click the test tab.

7. Verify that the method ran successfully. (It should give you feedback.)


Movement of Data.fs file to a new $$version$$ instance
------------------------------------------------------

For this step, you will move the Data.fs file from the old instance to
the new instance. First of all, install an eduCommons-$$version$$
instance using the installations instructions found in [new instance home]/eduCommons/docs/. Stop both sites. Then
copy the Data.fs file from the var directory of the old site to the
var/filestorage directory of the new site:
::

  sudo cp -rvfp [old instance home]/var/Data.fs [new instance home]/var/filestorage


Migration to eduCommons $$version$$ instance
------------------------------------------------
eduCommons $$version$$ uses the portal_setup tool to perform the necessary upgrade from 3.1.1 to $$version$$. Due to the fact that eduCommons and it's dependencies were moved to python eggs, we must start with a new eduCommons site. The migration script will then copy and past content and relevant settings to the new installation:

1. Navigate to the root of your ZMI instance and create a new eduCommons site called eduCommons321
2. Open your new $$version$$ eduCommons site in the ZMI. (click educommons Setup, then click Zope Management Interface.)
3. Navigate to portal_setup
4. Press the 'Upgrades' tab
5. From the drop down menu, select 'Products.eduCommons:default' and click Choose Profile button.
6. Choose the 'Migration :: 3.1.1 to 3.2.1' option
7. Press Upgrade


Export/Import of eduCommons site to a new $$version$$ instance
--------------------------------------------------------------

You are now ready to transfer your migrated instance to the production environment.  

1. Navigate to the root of your ZMI instance
2. Select the checkbox next to your new $$version$$ eduCommons site
3. Press Import/Export
4. If your production environment is on the same server as your migration environment, choose 'Save file to server', else
   Download the file to your local machine. Dependent on the size of your site, this process may take a long time.
5. Move the .zexp into the import directory of your production site [production_site]parts/instance/import
6. Navigate to the ZMI of your production site
7. Press Import/Export
8. Select your .zexp from the drop down list, and press Import. Dependent on the size of your site, this process may take a long time.
9. If desired, rename your imported eduCommons321 site.

Final Steps
-----------

Your site should now be migrated. Navigate to your site in the browser and ensure it has migrated.


