Changeset 3299
- Timestamp:
- May 7, 2007, 3:13:27 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/admindoc/installation_upgrade.xml
r3292 r3299 31 31 32 32 <title>Installation, migration, and upgrade instructions</title> 33 34 <note> 35 These instructions apply only to the BASE release which this 36 document is a part of. 37 </note> 33 38 34 39 <para> … … 49 54 </para> 50 55 51 <note> 52 These instructions apply only to the BASE release which this 53 document is a part of. 54 </note> 55 56 <sect1 id="installation_upgrade.upgrade"> 57 <title>Upgrade instructions</title> 58 59 <important> 60 Note to PostgreSQL users: Upgrading BASE to versions earlier 61 than v2.2 is not be safe with an PostgreSQL database engine 62 due to a bug in Hibernate. The problem is reported to 63 Hibernate developers. There now exists a workaround for this 64 problem. Read more about the workaround on 65 the <ulink 66 url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a 67 Postgres database prior to BASE 2.2</ulink> page. This fix is 68 not needed for the release which this document is a part of. 69 </important> 70 71 <para> 72 As always, backup your database before attempting an 73 upgrade. The BASE team performs extensive testing before 74 releasing a new version of BASE but there are always a 75 possibility for unexpected events during upgrades. In upgrades 76 requiring a change in the underlying database there is no 77 (supported) way to revert to a previous version of BASE using 78 BASE tools, you need to use your backup for this use case. 79 </para> 80 81 <para> 82 The strategy here is to install the new BASE release to 83 another directory than the one in use. This requires transfer 84 of configuration settings to the new install but more on that 85 below. 86 </para> 87 88 <variablelist> 89 <varlistentry> 90 <term>Shut down the tomcat server</term> 91 <listitem> 92 <para> 93 If the BASE application is not shut down already, it is 94 time to do it now. Do something like <command>sudo 95 /etc/init.d/tomcat5.5 stop</command> 96 </para> 97 </listitem> 98 </varlistentry> 99 100 <varlistentry> 101 <term>Rename your current server</term> 102 <listitem> 103 <para> 104 Rename your current BASE 2 installation <command>mv 105 /path/to/base /path/to/base_old</command>. 106 </para> 107 </listitem> 108 </varlistentry> 109 110 <varlistentry> 111 <term>Download and unpack BASE</term> 112 <listitem> 113 <para> 114 There are severeal ways to download BASE. Please refer 115 to section 116 <xref linkend="resources.home_page.download"/> for 117 information on downloading BASE, and select the item 118 matching your download option: 119 </para> 120 121 <variablelist> 122 <varlistentry> 123 <term><emphasis>Pre-compiled package</emphasis></term> 124 <listitem> 125 <para> 126 If you selected to download a pre-compiled 127 package, unpack the downloaded file 128 with <command>tar zxpf base-...tar.gz</command>. 129 </para> 130 </listitem> 131 </varlistentry> 132 133 <varlistentry> 134 <term><emphasis>Source package</emphasis></term> 135 <listitem> 136 <para> 137 If you selected to download a source package, 138 unpack the downloaded file with <command>tar zxpf 139 base-...src.tar.gz</command>. Change to the new 140 direcotry, and issue <command>ant 141 package.bin</command>. This will create a binary 142 package in the current directory. Unpack this new 143 package (outside of the source file hierarchy). 144 </para> 145 </listitem> 146 </varlistentry> 147 148 <varlistentry> 149 <term><emphasis>Subversion checkout</emphasis></term> 150 <listitem> 151 <para> 152 This option is for advanced users only and is not 153 covered here. Please refer 154 to <ulink 155 url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the 156 builing BASE document</ulink> for information on 157 this download option. 158 </para> 159 </listitem> 160 </varlistentry> 161 162 </variablelist> 163 </listitem> 164 165 </varlistentry> 166 167 <varlistentry> 168 <term>Transfer files and settings</term> 169 <listitem> 170 <para> 171 Settings from the previous installation must be 172 transferred to the new installation. This is most easily 173 done by comparing the configuration files from the 174 previous install with the new files. Do not just copy 175 the old files to the new install since new options may 176 have appeared. 177 </para> 178 <para> 179 In the main BASE configuration file, 180 <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>, 181 fields that needs to be transferred are usually 182 <emphasis>db.username</emphasis>, 183 <emphasis>db.password</emphasis>, 184 and <emphasis>userfiles</emphasis>. 185 </para> 186 <para> 187 Local settings in the raw data 188 tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>, 189 may need to be transferred. 190 </para> 191 </listitem> 192 </varlistentry> 193 194 <varlistentry> 195 <term>Updating database schema</term> 196 <listitem> 197 <para> 198 It is recommended that you also perform an update of 199 your database schema. Running the update scripts are 200 not always necessary when upgrading BASE, but the 201 running the update scripts are safe even in cases when 202 there is no need to run them. Change directory 203 to <filename 204 class="direcotry">/path/to/base/bin/</filename> and 205 issue 206 <command> 207 <literallayout>sh ./updatedb.sh <emphasis>base_root_password</emphasis> 208 sh ./updateindexes.sh <emphasis>base_root_password</emphasis></literallayout> 209 </command> 210 where <emphasis>base_root_password</emphasis> is the 211 password for the root user account within the BASE 212 application. 213 </para> 214 </listitem> 215 </varlistentry> 216 217 <varlistentry> 218 <term>Remove tomcat cache</term> 219 <listitem> 220 <para> 221 As tomcat user, remove cached files and directories. Do 222 something like 223 <command> 224 <literallayout>cd /usr/share/apache-tomcat-5.5.15/ 225 rm -rf work/Catalina</literallayout> 226 </command> 227 </para> 228 </listitem> 229 </varlistentry> 230 231 <varlistentry> 232 <term>Start tomcat</term> 233 <listitem> 234 <para> 235 Start the tomcat server: 236 <command> 237 <literallayout>sudo /etc/init.d/tomcat5.5 start</literallayout> 238 </command> 239 </para> 240 </listitem> 241 </varlistentry> 242 243 </variablelist> 244 245 <para> 246 Done! Upgrade of BASE is finished. 247 </para> 248 249 </sect1> <!-- Upgrade instructions --> 250 251 252 <sect1 id="installation_upgrade.isntallation"> 253 <title>Installation instructions</title> 254 <para></para> 255 </sect1> 256 257 258 <sect1 id="installation_upgrade.migration"> 259 <title>Migration instructions</title> 260 <para></para> 261 </sect1> 56 <para> 57 The instructions here assume 58 that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used 59 on the server side. Other servlet engines may work but we only 60 test tomcat. 61 </para> 62 63 64 <sect1 id="installation_upgrade.upgrade"> 65 <title>Upgrade instructions</title> 66 67 <important> 68 Note to PostgreSQL users: Upgrading BASE to versions earlier 69 than v2.2 is not be safe with an PostgreSQL database engine due 70 to a bug in Hibernate. The problem is reported to Hibernate 71 developers. There now exists a workaround for this problem. Read 72 more about the workaround on 73 the <ulink 74 url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a 75 Postgres database prior to BASE 2.2</ulink> page. This fix is 76 not needed for the release which this document is a part of. 77 </important> 78 79 <para> 80 As always, backup your database before attempting an 81 upgrade. The BASE team performs extensive testing before 82 releasing a new version of BASE but there are always a 83 possibility for unexpected events during upgrades. In upgrades 84 requiring a change in the underlying database there is no 85 (supported) way to revert to a previous version of BASE using 86 BASE tools, you need to use your backup for this use case. 87 </para> 88 89 <para> 90 The strategy here is to install the new BASE release to another 91 directory than the one in use. This requires transfer of 92 configuration settings to the new install but more on that 93 below. 94 </para> 95 96 <variablelist> 97 <varlistentry> 98 <term>Shut down the tomcat server</term> 99 <listitem> 100 <para> 101 If the BASE application is not shut down already, it is 102 time to do it now. Do something like <command>sudo 103 /etc/init.d/tomcat5.5 stop</command> 104 </para> 105 </listitem> 106 </varlistentry> 107 108 <varlistentry> 109 <term>Rename your current server</term> 110 <listitem> 111 <para> 112 Rename your current BASE 2 installation <command>mv 113 /path/to/base /path/to/base_old</command>. 114 </para> 115 </listitem> 116 </varlistentry> 117 118 <varlistentry> 119 <term>Download and unpack BASE</term> 120 <listitem> 121 <para> 122 There are severeal ways to download BASE. Please refer to 123 section <xref linkend="resources.home_page.download"/> for 124 information on downloading BASE, and select the item 125 matching your download option: 126 </para> 127 128 <variablelist> 129 <varlistentry> 130 <term><emphasis>Pre-compiled package</emphasis></term> 131 <listitem> 132 <para> 133 If you selected to download a pre-compiled package, 134 unpack the downloaded file with <command>tar zxpf 135 base-...tar.gz</command>. 136 </para> 137 </listitem> 138 </varlistentry> 139 140 <varlistentry> 141 <term><emphasis>Source package</emphasis></term> 142 <listitem> 143 <para> 144 If you selected to download a source package, unpack 145 the downloaded file with <command>tar zxpf 146 base-...src.tar.gz</command>. Change to the new 147 direcotry, and issue <command>ant 148 package.bin</command>. This will create a binary 149 package in the current directory. Unpack this new 150 package (outside of the source file hierarchy). 151 </para> 152 </listitem> 153 </varlistentry> 154 155 <varlistentry> 156 <term><emphasis>Subversion checkout</emphasis></term> 157 <listitem> 158 <para> 159 This option is for advanced users only and is not 160 covered here. Please refer 161 to <ulink 162 url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the 163 builing BASE document</ulink> for information on 164 this download option. 165 </para> 166 </listitem> 167 </varlistentry> 168 169 </variablelist> 170 </listitem> 171 172 </varlistentry> 173 174 <varlistentry> 175 <term>Transfer files and settings</term> 176 <listitem> 177 <para> 178 Settings from the previous installation must be 179 transferred to the new installation. This is most easily 180 done by comparing the configuration files from the 181 previous install with the new files. Do not just copy the 182 old files to the new install since new options may have 183 appeared. 184 </para> 185 <para> 186 In the main BASE configuration file, 187 <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>, 188 fields that needs to be transferred are usually 189 <emphasis>db.username</emphasis>, 190 <emphasis>db.password</emphasis>, 191 and <emphasis>userfiles</emphasis>. 192 </para> 193 <para> 194 Local settings in the raw data 195 tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>, 196 may need to be transferred. 197 </para> 198 </listitem> 199 </varlistentry> 200 201 <varlistentry> 202 <term>Updating database schema</term> 203 <listitem> 204 <para> 205 It is recommended that you also perform an update of your 206 database schema. Running the update scripts are not 207 always necessary when upgrading BASE, but the running the 208 update scripts are safe even in cases when there is no 209 need to run them. Change directory 210 to <filename 211 class="direcotry">/path/to/base/bin/</filename> and issue 212 <programlisting> 213 sh ./updatedb.sh <emphasis>base_root_password</emphasis> 214 sh ./updateindexes.sh <emphasis>base_root_password</emphasis> 215 </programlisting> 216 where <emphasis>base_root_password</emphasis> is the 217 password for the root user account within the BASE 218 application. 219 </para> 220 </listitem> 221 </varlistentry> 222 223 <varlistentry> 224 <term>Remove tomcat cache</term> 225 <listitem> 226 <para> 227 As tomcat user, remove cached files and directories. Do 228 something like 229 <programlisting> 230 cd /usr/share/apache-tomcat-5.5.15/ 231 rm -rf work/Catalina 232 </programlisting> 233 </para> 234 </listitem> 235 </varlistentry> 236 237 <varlistentry> 238 <term>Start tomcat</term> 239 <listitem> 240 <para> 241 Start the tomcat server: <command>sudo 242 /etc/init.d/tomcat5.5 start</command> 243 </para> 244 </listitem> 245 </varlistentry> 246 247 </variablelist> 248 249 <para> 250 Done! Upgrade of BASE is finished. 251 </para> 252 253 </sect1> <!-- Upgrade instructions --> 254 255 256 257 258 <sect1 id="installation_upgrade.installation"> 259 <title>Installation instructions</title> 260 261 <variablelist> 262 <varlistentry> 263 <term>Set up SQL database</term> 264 <listitem> 265 <para> 266 BASE 2 267 utilize <ulink 268 url="http://www.hibernate.org/">Hibernate</ulink> for 269 object persistence to a relational database. Hibernate 270 supports many database engines, but so far we only work 271 with <ulink url="http://www.mysql.com">MySQL</ulink> 272 and <ulink 273 url="http://www.postgresql.org/">PostgreSQL</ulink>. 274 </para> 275 276 <variablelist> 277 <varlistentry> 278 <term>MySQL</term> 279 <listitem> 280 <para> 281 Download and install MySQL (tested with version 282 5.0), available from 283 <ulink 284 url="http://www.mysql.com/">http://www.mysql.com/</ulink>. You 285 need to be able to connect to the server over TCP, 286 so the <emphasis>skip-networking</emphasis> option 287 must <command>not</command> be used. The InnoDB 288 table engine is also needed, so don't disable them 289 (not that you would) but you may want to tune the 290 InnoDB behaviour before creating BASE 291 databases. BASE comes pre-configured for MySQL so 292 there is no need to change database settings in the 293 BASE configuration files. 294 </para> 295 </listitem> 296 </varlistentry> 297 <varlistentry> 298 <term>PostgreSQL</term> 299 <listitem> 300 <para> 301 PostgreSQL 8.0 seems to be working very well with 302 BASE and Hibernate. Download and install PostgreSQL, 303 avaialble 304 from <ulink 305 url="http://www.postgresql.org/">http://www.postgresql.org/</ulink>. you 306 must edit 307 your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename> 308 file. Uncomment the settings for Postgres and 309 comment out the settings for MySQL. 310 </para> 311 </listitem> 312 </varlistentry> 313 </variablelist> 314 315 </listitem> 316 </varlistentry> 317 318 <varlistentry> 319 <term>Java</term> 320 <listitem> 321 <para> 322 Download and install Java SDK 1.5, available 323 from <ulink 324 url="http://java.sun.com/">http://java.sun.com/</ulink>. Make 325 sure that you download the JDK version 326 (<emphasis>not</emphasis> the JRE version). <command>Java 327 6 is currently not supported</command>. 328 </para> 329 </listitem> 330 </varlistentry> 331 332 <varlistentry> 333 <term>BASE (download and unpacking)</term> 334 <listitem> 335 <para> 336 <ulink 337 url="http://base.thep.lu.se/wiki/DownloadPage">Download 338 BASE</ulink> and unpack the downloaded file, 339 i.e. <command>tar zxpf base-...tar.gz</command>. If you 340 prefer to have the bleeding edge version of BASE, perform 341 a checkout of the source from the subversion repository 342 (subversion checkout instructions at 343 <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE 344 trac site</ulink>). 345 </para> 346 <para> 347 If you choose to download the binary package, skip to the 348 next item. The rest of us, read on and compile BASE 2. If 349 you downloaded a source distribution, unpack the 350 downloaded file <command>tar zxpf 351 base-...src.tar.gz</command>, or you may have performed a 352 subversion checkout. Change to the 'root' base2 353 directory, and issue <command>ant 354 package.bin</command>. This will create a binary package 355 in the base2 'root' directory. Unpack this new package 356 (outside of the source file hierarchy), and from now on 357 the instructions are the same irrespective where you got 358 the binary package. 359 </para> 360 <para> 361 <emphasis>This section is intended for advanced users and 362 programmers only. In cases when you want to change the 363 BASE code and try out personalized features it may be 364 advantageous to run the tweaked BASE server against the 365 development tree. Instructions on how to accomplish this 366 is available in the 367 <ulink 368 url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building 369 BASE document</ulink>. When you return back after 370 compiling in the subversion tree you can follow the 371 instruction here (with obvious changes to 372 paths).</emphasis> 373 </para> 374 </listitem> 375 </varlistentry> 376 377 <varlistentry> 378 <term>BASE (database engine)</term> 379 <listitem> 380 <para> 381 Instructions for MySQL and PostgreSQL are available 382 below. The database names, the <emphasis>user</emphasis>, 383 and the <emphasis>password</emphasis> can be changed 384 during the creation of the databases. It is recommended to 385 change the <emphasis>password</emphasis>, the other 386 changes can be made if required. The database names, 387 the <emphasis>user</emphasis>, and 388 the <emphasis>password</emphasis> are needed in a later 389 step below when configuring BASE. 390 </para> 391 <variablelist> 392 <varlistentry> 393 <term>MySQL</term> 394 <listitem> 395 <para> 396 Create a new database for BASE, and add a 397 <emphasis>user</emphasis> with at least 398 <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>, 399 <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>, 400 <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>, 401 <emphasis>INDEX</emphasis>, 402 and <emphasis>ALTER</emphasis> permission for the 403 new database. To do this, connect to your MySQL 404 server and issue the next lines: 405 <programlisting> 406 CREATE DATABASE base2; 407 CREATE DATABASE base2dynamic; 408 GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password'; 409 GRANT ALL ON base2dynamic.* TO base2user@localhost; 410 </programlisting> 411 </para> 412 <para> 413 The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename> 414 file contains the above statements and can be used 415 by the <filename>mysql</filename> command-line tool 416 (remember to edit 417 the <emphasis>user</emphasis>, <emphasis>password</emphasis>, 418 and the database names in the script file before 419 executing the command): <command>mysql -uroot -p 420 < ./misc/sql/createdb.mysql.sql</command>. The 421 header in the script file contains further 422 information about the script. 423 </para> 424 </listitem> 425 </varlistentry> 426 <varlistentry> 427 <term>PostgreSQL</term> 428 <listitem> 429 <para> 430 Create a new database for BASE, and add a 431 <emphasis>user</emphasis> with the proper 432 privileges. To do this, log in as your PostgreSQL 433 user and issue these lines (omit comments): 434 <programlisting> 435 createuser base2user -P 436 # this will prompt for an password for the new user, and issue two 437 # more question that should be answered with character 'n' for no. 438 createdb --owner base2user --encoding UNICODE base2 439 psql base2 440 # this will start the psql command line tool. Issue the next line 441 # within the tool and quit with a '\q'. 442 CREATE SCHEMA "dynamic" AUTHORIZATION "base2user"; 443 </programlisting> 444 The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename> 445 file contains the above statements and can be used 446 by the <filename>psql</filename> command-line tool: 447 <command>psql -f ./misc/sql/createdb.posgres.sql 448 template1</command> The header in the script file 449 contains further information about the script. 450 </para> 451 </listitem> 452 </varlistentry> 453 </variablelist> 454 </listitem> 455 </varlistentry> 456 457 <varlistentry> 458 <term>BASE (file storage setup)</term> 459 <listitem> 460 <para> 461 An area for file storage must be setup. Create an empty 462 directory in a proper location in your file system, and 463 set the owner to be the same as the one that the tomcat 464 server will be running as. Remember this location for 465 later use. 466 </para> 467 </listitem> 468 </varlistentry> 469 470 <varlistentry> 471 <term>BASE (configuration)</term> 472 <listitem> 473 <para> 474 </para> 475 </listitem> 476 </varlistentry> 477 478 <varlistentry> 479 <term></term> 480 <listitem> 481 <para> 482 </para> 483 </listitem> 484 </varlistentry> 485 </variablelist> 486 487 488 </sect1> <!-- Installation instructions --> 489 490 491 <sect1 id="installation_upgrade.migration"> 492 <title>Migration instructions</title> 493 <para></para> 494 </sect1> <!-- Migration instructions --> 262 495 263 496 </chapter>
Note: See TracChangeset
for help on using the changeset viewer.