Changeset 3355 for trunk/doc/src/docbook/admindoc/installation_upgrade.xml

Timestamp:

May 21, 2007, 4:40:49 PM (16 years ago)

Author:

Jari Häkkinen

Message:

Addresses #516. Migration instructions done.

File:

• trunk/doc/src/docbook/admindoc/installation_upgrade.xml (modified) (3 diffs)

trunk/doc/src/docbook/admindoc/installation_upgrade.xml

@@ -66 +66 @@
 
     <important>
-      Note to PostgreSQL users: Upgrading BASE to versions earlier
+      <title>Note to PostgreSQL users</title>
+      Upgrading BASE to versions earlier
       than v2.2 is not be safe with an PostgreSQL database engine due
       to a bug in Hibernate. The problem is reported to Hibernate
@@ -252 +253 @@
 
   </sect1>      <!-- Upgrade instructions -->
-
-
 
 
@@ -685 +684 @@
   <sect1 id="installation_upgrade.migration">
     <title>Migration instructions</title>
-    <para></para>
+
+    <caution>
+      <title>The disclaimer section</title>
+      <para>
+        We have made extensive testing of the migration from BASE1.2
+        to BASE2. To our knowledge the migration works but we cannot
+        guarantee perfect functionality. The migration tool is
+        supplied as is and usage is done at your risk. We are
+        committed to solve migration problems at the level of
+        transferring data from BASE 1.2 to 2.2.x, but cannot resolve
+        data loss issues in a running BASE 2 server due to imperfect
+        migration. When you start the migration tool you are required
+        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
+        to the <filename>migrate_from_1.2.sh</filename>
+        script. Remember to check that the migration performed well
+        before you decide to delete your 1.2 installation.
+      </para>
+      <para>
+        Migration from the latest BASE 1.2.x release to the latest is
+        supported.
+      </para>
+    </caution>
+
+    <para>
+      Verify that your BASE 2 installation is up and running before
+      attempting migration. Preferably try to log in using the root
+      user through the web interface.
+    </para>
+
+    <para>
+      Make sure your BASE 1.2 runs with the latest
+      (<emphasis>pristine</emphasis>) schema
+      version, <emphasis>i.e.,</emphasis> the migration will only
+      support an unmodified BASE 1.2 installation. If you have an out
+      of date schema version, please upgrade to the latest schema
+      using BASE 1.2 tools before migrating. If you have made local
+      changes to the BASE 1.2 schema you need to patch the BASE 2
+      schema as well as make proper changes to the migration program.
+    </para>
+
+    <para>
+      There is currently no way to restart a migration. The behaviour
+      of migration is controlled
+      through <filename>migration.properties</filename> file, but you
+      should know what you do when you change parameters in this file.
+    </para>
+
+    <para>
+      Migration is performed with the following steps:
+      <orderedlist>
+
+        <listitem>
+          <para>
+            To transfer files from BASE 1.2 (default migration
+            behaviour), you must have file system access to BASE 1.2
+            files, <emphasis>i.e.,</emphasis> the <filename
+            class="directory">/path/to/base1.2/data</filename>
+            directory containing directories
+            <filename class="direcotry">rawdata</filename>,
+            <filename class="direcotry">uploads</filename>,
+            <filename class="direcotry">protocols</filename>, ...
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Change settings in the file
+            <filename>/path/to/base/dist/www/WEB-INF/classes/migrate.properties</filename>.
+            The available options are commented:
+            <itemizedlist>
+              <listitem>
+                <para>
+                  Modify <emphasis>db1.*</emphasis> parameters to
+                  match your BASE 1.2 installation.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  Set <emphasis>userfiles</emphasis> (note, this is
+                  not the same parameter as
+                  in <filename>base.config</filename>) to point to the
+                  directory containing the BASE 1.2 files (defined in a
+                  previous step above).
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  Set the <emphasis>pluginDir</emphasis> to point to
+                  the directory where your BASE 1.2 plug-ins are
+                  installed. The default is
+                  <filename
+                  class="direcotry">/usr/local/base/plugins</filename>.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  Modify <emphasis>root.password</emphasis>.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  Change the <emphasis>deletefiles</emphasis> setting
+                  wisely. If you
+                  set <emphasis>deletefiles=yes</emphasis> all BASE
+                  1.2 files will be physically removed when copied to
+                  BASE 2. Leave this options
+                  as <emphasis>deletefiles=no</emphasis> unless you
+                  are absolutely sure of what you are doing.
+                </para>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Run migration utility: <programlisting>
+cd /path_to_base/dist/bin
+./migrate_from_1.2.sh
+</programlisting>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Migration done! Happy BASEing.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+    </para>
+
   </sect1>      <!-- Migration instructions -->
+
+
 
   <sect1 id="installation_upgrade.jobagents">