Upgrade 1.5.1 to 2.3.1 on OS X Yosemite - Lessons Learned

In a small effort to give back to the community here are a few things we learned in upgrading Omeka from version 1.5.1 to 2.3.1. Our installation involves OS X, both on the original 1.5.1 machine and on the new Mac Mini we’re using for 2.3.1. The install took time, patience, and some technical knowledge (but not too much) but in the end Omeka runs very well on our OS X Mac Mini under OS X 10.10.5 Yosemite.

Suggestions…
1. Read the preparation and installation guides in the omeka.org documentation section several times. Be sure the backup on the old machine is working before doing anything else. Once there is a current backup put that away. Use a different portable drive for the transfer process.

2. Read the directions at omeka.org on Moving to Another Server. Using phpMyAdmin (if you have that installed) or the command line (the Terminal app on OS X), export your mysql database to your portable drive. We compressed ours as a zip file. Next, copy the files/folders to your portable drive as directed in step 4 of the Moving to Another Server guide.

3. Preparing the new server. Our particular install was on a new Mac Mini running OS X Yosemite, 10.10.5. We also run the “Server” app, which allows remote management.

4. OS X has most of the components Omeka needs available except for mysql and phpmyadmin. The following guide was very helpful in getting those set up properly: http://coolestguidesontheplanet.com/get-apache-mysql-php-phpmyadmin-working-osx-10-10-yosemite/ The guide covers other changes that aren’t needed; only the steps for mysql and phpmyadmin are essential for this project.

5. On the new server find the web server directory. The default location is /Library/Server/Web/Data/Sites/Default. Create a directory in the /Default directory for your new install. Download the latest Omeka files and copy them to this directory. On an OS X install you probably dragged the files into place. If so, note that OS X does not show users files that start with a . and this includes the .htaccess file that is an essential part of the Omeka install. Use the command line (the Terminal app) to copy this file into place. This is also a good time to edit the .htaccess file to remove the # on the ENV line to allow error reporting.

6. Move your old data files to the new server directory. If your install is old like ours you’ll need to rename the directories as described in Moving to Another Server. Change the permissions on these files. The directions for the command line (Terminal App) will work OR you can use command-i to see the permissions in the Mac graphical interface. We set the first two (the owner and the group) to Read & Write permission. we set the third “everyone” group to only have “read only” access. If using the graphical interface use the “gear” icon that lets you set all enclosed items to the same permissions (that’s what the -R flag does in the command line). These settings worked for our install, but how these permissions are set is something to discuss with your IT staff since there are security implications to your choices. Get advice if unsure.

7. In phpmyadmin create a new database. We used collation type UTF8-bin. Make a user with the same name as the database. Check the Global privileges “All” box and click “go” to create the user.

8. In phpmyadmin, select the database created in step 7. Use the import option to import the zipped mysql file created in step 2.

9. Edit the db.ini file so it matches the database and user created in step 7. Save the file. Watch out for editors that change the straight quotation marks into curly quotation marks. The installation will fail if the db.ini file has curly quotes.

10. SEE IF IT WORKED: Use a web browser to see the new installation: localhost/nameofyourinstallation/admin If an “upgrade the database” button or the standard admin login box appears then your install worked!

RECAP and KEY OBSERVATIONS:
Be ready with at least one good backup of your data. We deliberately did not upgrade our existing installation so our only working copy wouldn't potentially be lost. Instead we copied the data and used that on a new machine with a new installation.
For OS X watch for that .htaccess file since it doesn’t show up automatically.
The order of installation really matters. What tripped us up multiple times was step one of “Moving to Another Server” which says to install a blank version of the latest Omeka. We read this as ‘install the Omeka files, create a database and user, edit the db.ini and run the Install files’, then do the import of the old data. FOR US THIS TURNED OUT TO BE THE WRONG ORDER. The key is to use the order listed above in steps 6, 7, 8 so that the new blank database is created and the old data imported into it before trying to run the new instance of Omeka. With this transfer/upgrade we never actually ran the Install files.

Good Luck!

We read this as ‘install the Omeka files, create a database and user, edit the db.ini and run the Install files’, then do the import of the old data. FOR US THIS TURNED OUT TO BE THE WRONG ORDER. The key is to use the order listed above in steps 6, 7, 8 so that the new blank database is created and the old data imported into it before trying to run the new instance of Omeka. With this transfer/upgrade we never actually ran the Install files.

Yes, the order you're describing here of making a backup of the old database and importing that backup into the new server first and not actually running the installer for the new version, that's the correct steps and order.

I'll take a look at the Moving to Another Server instructions to see if we can make them clearer on that point. It's possible we're playing fast and loose with the word "install" somewhere we shouldn't be.

Okay, I can definitely see how the old instructions would be misleading.

I've tried to clear them up by reordering and rewording the instructions a little, as well as removing the explicit reference to the Installing instructions, which I think was probably the most confusing part.

John,
Thank you for looking this over and for clarifying the 'moving to another server' directions. I'd also like to thank you and the Omeka team for the attention to detail here as well as on the overall project. It is an impressive accomplishment. As for the directions I posted here, unless you see something really in need of correction I'd propose they stay here as a guide for Mac users. If other campuses are like ours, buying a server (or getting IT to run one) is hard but repurposing a recent mac mini or iMac is pretty common, especially for small projects or for a class.

As a last thought - I can't edit my posts, but perhaps you could change the title of my earlier "Transfer to new server / upgrade fails" post to "Resolved" with a pointer to this one.

Thanks again for your help!

If you just post another message on that other thread with a link to this one, I can come in and close that one.

Done!