-
Notifications
You must be signed in to change notification settings - Fork 66
Upgrading Roxy
We continue to make improvements to Roxy. Every now and then, you may want to upgrade an existing Roxy-based project to the latest version of Roxy. This page is not intended to get you from any version of Roxy to any later version of Roxy, but should cover most cases.
As of 2013-08-13, the dev branch of Roxy (version 1.4) includes an upgrade command. You can check whether you have it in your project by running $ ml -h and looking for "upgrade". If you do have it, you can run an upgrade like this:
$ ml upgrade --branch=dev
or
$ ml upgrade --branch=master
You can also upgrade to a fork of Roxy with a command like:
$ ml upgrade --branch=master --fork=marklogic
The assumptions described in the section below regarding version control and not having changed Roxy's files still hold. (You won't need a fresh copy of Roxy.) This command is an automated way of copying the files, as you would do manually using the procedure below.
Note that neither this command nor the procedure below removes files no longer used by Roxy.
If your project's files predate this feature, you may be able to automatically upgrade by copying the following files into your project:
These files may or may not work with older versions of Roxy. Proceed with caution.
I assume that you have
~/git/old-app/
~/git/roxy/
and both are up-to-date and have no local modifications. ~/git/roxy/ is a fresh copy of the version of Roxy you want to upgrade to -- this might be the latest on the master branch or you can go for the latest and get the dev branch. Note that you should not run "ml init" in the ~/git/roxy/ directory -- you want it just like it is here on GitHub.
Under the deploy directory, you should be working with build.properties, environment-specific properties files, ml-config.xml, and app_specific.rb. Only app_specific.rb will get overwritten by the procedure below (we'll handle that). You should explicitly not have edited default.properties, as noted in the comment at the top of that file.
Likewise, you should not have edited anything under src/roxy/.
Naturally, your application is under version control, so it will be easy to see what changed and revert any accidents.
There is one file you might have changed that will get overwritten in this procedure.
- deploy/app_specific.rb
There are two simple ways to handle this.
- Do the copy commands below, then use "$ git checkout deploy/app_specific.rb" to restore your version.
- Make a copy of app_specific.rb, do the copy commands below, then copy your original back into place.
Here are the steps:
$ cd ~/git/old-app/
$ cp -r ~/git/roxy/deploy/* deploy
$ cp -r ~/git/roxy/src/roxy/* src/roxy
$ cp ~/git/roxy/ml .
$ cp ~/git/roxy/ml.bat .
$ cp ~/git/roxy/version.txt .
$ cp ~/git/roxy/CHANGELOG.mdown .
For environments where you have a lot of data loaded, or that other people are using, there's no need to do anything further. However, with at least one environment, you'll want to make sure that your updated code and configuration work completely. You can test by doing the following steps (I'm using the local environment to test):
# THIS WILL FULLY REMOVE YOUR APP FROM MARKLOGIC -- SOURCE AND DATA
$ ml local wipe
# You will be told you need to restart MarkLogic. Assuming so:
$ ml local restart
$ ml local bootstrap
If the bootstrap doesn't result in the full setup that you expect, try it with the verbose flag:
$ ml local bootstrap -v
Once that works, deploy your modules, cpf (if necessary), content and test your app.
- Verify that your configuration files didn't get stomped.
- For MVC and Hybrid apps, the old version of the app might not have had the src/roxy/config/defaults.xqy, which is where some of the default configuration is now set up. Compare ~/git/roxy/src/app/config/config.xqy to your src/app/config/config.xqy. If your old version is old enough, you may need to manually revise your config.xqy to be like what's now distributed.