| blob | 273f6ddfa96abb21b6c3415dbdc1ab19ff4e6c5b |
1 Ganymede Logo
3 Ganymede Upgrade Guide
4 Release 2.0 - 1 April 2008
6 --------------------------------------------------------------------------
8 Note: If you are reading this as the UPGRADE text file in the Ganymede
9 distribution directory, you are missing a bunch of hyper-links that link
10 to extra information about many topics discussed. If you can, view this
11 document with a web browser as doc/upgrade.html.
13 +------------------------------------------------------------------------+
14 |Upgrading Ganymede |
15 +------------------------------------------------------------------------+
17 Upgrading Ganymede generally amounts to upgrading the jar files that
18 contain the Java class files that make up the Ganymede server and clients.
19 When a new release of Ganymede comes out, you'll generally want to upgrade
20 your server and your clients together, as it is sometimes necessary to
21 make incompatible changes to the network API's that the clients use to
22 talk to the server between versions of the Ganymede distribution.
24 Upgrading the clients is extremely easy, as there is almost never anything
25 to be done other than to replace the client jar files. Sometimes the
26 support files that are used to launch the clients may change. At the
27 worst, you can simply delete the old clients and re-install. More on this
28 later.
30 The hardest thing to upgrade is the schema kit that takes care of backend
31 network updates when transactions are committed in the Ganymede server.
32 Generally, the backend scripts that take files emitted by the Ganymede
33 server and propagate them into your network are heavily customized for
34 local use, and you will not want to lose that work. We'll go into greater
35 detail on this as well.
37 +------------------------------------------------------------------------+
38 |Upgrading the Ganymede Server |
39 +------------------------------------------------------------------------+
41 The first thing to do when upgrading the Ganymede server is to make a
42 backup copy of your existing server installation. Shut down your existing
43 server, create a tar file of your existing server directory, and put it in
44 a safe place. You may also want to use the xml client to dump a copy of
45 your current database to an XML file for safekeeping, just in case.
47 Note that it's very important to shut down your existing server cleanly
48 before performing an upgrade. The database file format may change slightly
49 between versions of the Ganymede server, and Ganymede's data loading
50 routines currently take more care at handling version differences when
51 reading the ganymede.db file than when reading the transaction journal.
52 Cleanly shutting down the server gives the server an opportunity to
53 coalesce all transactions into the ganymede.db file, and will help avoid
54 problems in the upgrade.
56 Now, assuming you've done a clean shutdown of your old server and made
57 backup copies of everything, you'll want to take the new Ganymede
58 distribution and unpack it, configure it, and run installServer to install
59 the new server code into a scratch directory.
61 Once you have installed the new server into a scratch directory, you can
62 go ahead and copy the new ganymede.jar and ganymedeServer.jar from the
63 scratch directory's jars directory into your existing server's jars
64 directory.
66 That is generally all that you will have to do to upgrade your server. The
67 Ganymede server is designed to retain upward compatiblity with all of its
68 data files, including especially the ganymede.db file. Newer servers can
69 load and use ganymede.db files from any version of Ganymede released in
70 the last couple of years, but if you are upgrading from a very old release
71 (before 0.99), you may have problems. If worst comes to worst, we've got
72 that backup copy of everything.
74 The more typical problem you'll encounter is a compatibility problem
75 between the schema kit you have installed and the new ganymedeServer.jar
76 file. The custom code in a custom.jar file is meant to be compiled against
77 the contents of a specific ganymedeServer.jar file, and it is good
78 practice to recompile your custom code, just to be sure.
80 Assuming that you are using a schema kit that is structured in the same
81 way as the Ganymede 1.0 userKit, the way to do this is to cd to
82 <server>/schema/src and run the build and buildJar scripts. If the build
83 and buildJar scripts compile and install your code without problems, you
84 are probably done with the server upgrade.
86 If not, take your backup copy and restore the original state of the
87 <server> directory from your backup.
89 Keep in mind during all of this that all of the server scripts are custom
90 configured to run in the location in which they are installed. If you try
91 running your backup copy in a different location than it was originally
92 installed, you'll find things not working properly. The jar files don't
93 care, obviously, but don't think that the server you installed in the
94 scratch directory can be moved to where your old server was running. If
95 you want to completely reinstall from scratch, install the server where
96 you want it from the beginning.
98 +------------------------------------------------------------------------+
99 |Upgrading the Schema Kit |
100 +------------------------------------------------------------------------+
102 It is possible, however, that your schema kit rebuild won't work properly.
103 This generally means that something in the server has changed in an
104 incompatible fashion. (This is, in fact, guaranteed to have happened if
105 you try and upgrade a schema kit designed for Ganymede 1.0 for use with a
106 Ganymede 2.0 server. See the 2.0 Upgrade document for details, there.)
107 Generally I try hard to avoid incompatible changes of this kind within a
108 major version series, but if it happens, it should be noted in the
109 Ganymede distribution's CHANGES file.
111 Alternately, it may be that your rebuild worked fine, but you have seen
112 that a new version of the schema kit that you are using has been released,
113 and you want to upgrade your schema kit, possibly even without upgrading
114 the server proper. This is a more tricky issue, as you will have
115 customized a lot of the files in your server's schema directory in order
116 to interconnect the files generated by Ganymede with your network.
118 This discussion will be assuming that you are using a schema kit patterned
119 after the Ganymede userKit. If you are using one of the pre-1.0 "schema
120 kits", like we use at ARL:UT, or if you have designed your own custom code
121 distribution without using the userKit as a template, you'll have to
122 figure out how to do this process by analogy.
124 Any schema kit upgrade you download should include a CHANGES file that
125 will warn you of any things you'll need to look out for in doing the
126 schema kit upgrade, as well as a description of what benefits you can
127 expect to see from performing the upgrade.
129 Before attempting to perform any schema kit upgrade, you will want to have
130 shut down and backed up your entire server directory, as discussed above.
131 Once this is done, you should rename the <server>/schema directory to
132 something like <server>/schema.save.
134 Once the schema directory has been renamed, you can run the installKit
135 script from the newly downloaded schemaKit distribution. installKit will
136 ask you for the name of the directory where your server is installed. Tell
137 it the location of your existing server directory, and installKit will
138 compile all of the custom code in the new schema kit against your server's
139 ganymedeServer.jar file, and integrate the new schema kit into your
140 existing server directory, creating a new schema directory underneath your
141 <server> directory, alongside your pre-existing schema.save directory.
143 If the installKit script fails for some reason, you haven't lost anything.
144 You can just delete the schema directory it was trying to create and
145 rename your schema.save directory back to schema to put the old schema kit
146 back in place.
148 Assuming it succeeds, though, you need to do the next step, which is to
149 migrate your backend scripts forward. In the simplest case, where you
150 don't care about any improvements in whatever backend scripts are provided
151 by the new schema kit, and the new schema kit's logic for interfacing with
152 its build scripts has not changed, you can generally just replace the new
153 schema kit's output directory with the output directory for your
154 schema.save directory. The Ganymede 1.0 userKit is designed so that all
155 files and scripts involved with the backend update process are stored in
156 the <server>/schema/output directory, so if you move your old output
157 directory forward, you should keep everything on the backend working just
158 as before.
160 If the new schema kit includes new features in the backend, you'll
161 probably want to either copy some of the scripts from the new kit's output
162 directory, or at the very least look at the files and see if you need or
163 want to make any manual edits to incorporate new features. Again, read the
164 CHANGES file in the new schema kit for details.
166 Once you have completed this process, you can start your server up again,
167 and all should be well. If not, you've got that backup copy, and you can
168 just recreate your <server> directory as it was before your attempted
169 upgrade.
171 +------------------------------------------------------------------------+
172 |Upgrading the Ganymede Clients |
173 +------------------------------------------------------------------------+
175 Upgrading the clients is a lot easier than upgrading the server, but you
176 will often need to do both at the same time. Upgrading the clients without
177 upgrading the server may cause a failure of the clients, as they attempt
178 to speak to the server using a newer version of the network API's than the
179 server can handle. If you upgrade the clients, you should plan on
180 upgrading the server, and vice versa, generally.
182 Again, before you do anything to your existing clients, you should make a
183 backup copy of everything. Upgrading the clients is easy, but if you find
184 that your server upgrade fails, you will need to revert the clients as
185 well as the server.
187 The easiest way to upgrade the clients is to simply delete the old clients
188 (scripts and jars and all) and re-run the installClient and installWeb
189 scripts from the new Ganymede distribution that you have downloaded.
191 If you have made significant local customizations to the client scripts or
192 web forms, you can do a more nuanced upgrade by just taking the new jar
193 files and incorporating them into your existing client directories.
195 In this case, all you need to do is to run installClient or installWeb to
196 get the new jar files installed into a scratch directory. Copy
197 ganymede.jar and ganymedeAdmin.jar from the scratch directory to your old
198 client directories, and you're set.
200 --------------------------------------------------------------------------
202 Jonathan Abbey