How to Migrate from pkContextCMS to Apostrophe

BEFORE YOU BEGIN

• PLEASE NOTE: you should DEFINITELY back up your site before you run the migration task! Back up your database and media files too, not just your code.
• This task will rename symbols beginning with pk throughout your application. If you make heavy use of this prefix in your own code, we recommend renaming those things first to avoid conflict.
• The migration task intelligently detects whether a particular folder is part of an svn checkout and uses svn commands rather than raw file manipulation commands in that folder. If you have a "halfhearted" svn checkout, such as an svn checkout of cmstest that you then started editing with plain vanilla file editing commands and have never checked into a real repository of your own, this may result in surprises for you. Delete the .svn subfolders from any folders in your project that are not really svn checkouts before you migrate. (Don't do this if you have a real svn project in a real repository!)
• The migration task leaves the plugins folder and the lib/vendor folder alone. This is by design. We assume you have not created your own plugins that contain references to our old plugins that need to be cleaned up. If you have, contact us to get the tools we use internally for that.
• Although the migration task uses svn commands like 'svn mv' if your project is in svn, it does NOT commit your project back to your repository on its own. This is by design. When the migration task finishes you will want to thoroughly test your site before you 'svn commit'.
• Your tables will be renamed. Your database.yml must have credentials that allow renaming and creating tables. The PDO SQL calls used to do this are fairly portable, but we've only tried it with MySQL. If it doesn't work for you with your non-MySQL database, check the task for the rename commands that need to be run in your database.
• There is a separate migration task for data on production servers and other boxes other than the initial box on which you migrate the code.
• This HOWTO largely assumes you are using svn, because that is part of our workflow. If you are not using version control the migration task should still work, automatically defaulting to vanilla file manipulation commands. If you are using a different version control system you may find it easiest to just run it on an export of your project and check in the finished result as a new folder in your alternate version control system.

How to Migrate to apostrophePlugin

ON YOUR DEV BOX

Edit the externals in the plugins/ folder

Remove the existing pk plugins (both the actual folders and the entries in the externals)

If pkBlogPlugin was present replace it with apostropheBlogPlugin:

apostropheBlogPlugin http://svn.apostrophenow.org/plugins/apostropheBlogPlugin/trunk

Add apostrophePlugin:

apostrophePlugin http://svn.apostrophenow.org/plugins/apostrophePlugin/trunk

svn update in the plugins folder

cd to the project's root folder

./symfony apostrophe:migrate-from-pkcontextcms

Now migrate your data as well (I am assuming your environment on your test box is the dev environment):

./symfony apostrophe:migrate-data-from-pkcontextcms --env=dev

Now test your site, a lot!

KNOWN ISSUE: for some reason you may wind up with real folders, not symlinks, for sfDoctrinePlugin, etc. in the web/ folder. We're not sure why yet. You can rm -rf these and run ./symfony plugin:publish-assets again. You will need to do that before svn commit will work.

Now do:

svn commit

The project is now upgraded. BUT the existing staging and production servers still need attention to rename their tables, change slot names in the slot table, rebuild search indices etc. (If this doesn't make sense to you, you probably haven't deployed your site to a server yet.)

ON THE STAGING AND PRODUCTION SERVERS, AND ON THE DEV BOXES OF COWORKERS (if they already have the old site running in their local Apache test environment)

First, add data/pk_writable back to config/rsync_exclude.txt so it won't try to remove it off the staging server etc.

Then, deploy your code to the staging server. You might be a symfony project:deploy fan, or an "svn checkout on the staging server" fan, or even a fan of our own apostrophe:deploy task, which carries out a project:deploy with additional steps to ensure no surprises:

./symfony apostrophe:deploy staging staging

Next, run:

./symfony apostrophe:migrate-data-from-pkcontextcms --env=staging

If data/pk_writable still contains anything other than our usual pk_tmp and search engine index folders, move it over manually to data/a_writable

Test your site.

Note that the migration tasks do symfony cc, build classes, etc. so you don't need to re-do those things (if you do have to it's a bug).

AFTER ALL COWORKERS HAVE MIGRATED THEIR DATA (or just synced it from someplace), you can remove the data/pk_writable folder from svn:

svn rm data/pk_writable

You should be good to go!