21.5. Migration instructions

[Caution] The disclaimer section

We have made extensive testing of the migration from BASE version 1.2 (BASE1.2) to BASE version 2 (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 BASE1.2 to BASE2, but cannot resolve data loss issues in a running BASE2 server due to imperfect migration. When you start the migration tool you are required to pass parameter "disclaimer_understood" to the migrate_from_1.2.sh script. Remember to check that the migration performed well before you decide to delete your 1.2 installation.

Since BASE 2.6 we no longer actively test or maintain the migration program. We still accept bug reports and will try to fix critical bugs, but only if we get help with testing the fixes before they are released. Supplying a patch for a bug will increase the chance of getting it fixed.

Verify that your new BASE installation is up and running before attempting migration. Preferably try to log in using the root user through the web interface.

Make sure your BASE1.2 runs with the latest (pristine) schema version, i.e., the migration will only support an unmodified BASE1.2 installation. If you have an out of date schema version, please upgrade to the latest schema using BASE1.2 tools before migrating. If you have made local changes to the BASE1.2 schema you need to patch the BASE2 schema as well as make proper changes to the migration program. If there are added columns to the reporter table in your BASE1.2 database you need to transfer the additional information after migration (even if you modified the BASE2 extended-properties.xml file).

The behaviour of migration is controlled through migration.properties file (see Appendix I, migrate.properties reference), but you should know what you do when you change parameters in this file.

Migration can be restarted in one specific case only; If the migration fails during the RawBioAssayData transfer simply restart the migration and the script will ask you to verify that a restart should be attempted. For all other failure points the migration has to be restarted with an empty database.

Migration is performed with the following steps:

  1. To transfer files from BASE1.2 (default migration behaviour), you must have file system access to BASE1.2 files, i.e., the /BASE 1.2/data directory containing directories rawdata, uploads, protocols, ...

  2. Change settings in the file <base-dir>/dist/www/WEB-INF/classes/migrate.properties. The available options are commented:

    • Modify db1.* parameters to match your BASE1.2 installation.

    • Set userfiles (note, this is not the same parameter as in base.config) to point to the directory containing the BASE1.2 files (defined in a previous step above).

    • Set the pluginDir to point to the directory where your BASE1.2 plug-ins are installed. The default is /usr/local/base/plugins.

    • Modify root.password.

    • Change the deletefiles setting wisely. If you set deletefiles=yes all BASE1.2 files will be physically removed when copied to the BASE2 server. Leave this options as deletefiles=no unless you are absolutely sure of what you are doing.

  3. Run migration utility:

    cd /path_to_base/dist/bin
    ./migrate_from_1.2.sh disclaimer_understood

    If the migration fails during the RawBioAssayData transfer you can restart the migration at the point of failure. Simply restart the migration and the script will ask you to verify that a restart should be attempted. For all other failure points the migration has to be restarted with an empty database.

  4. Optional, depends on your BASE1.2 reporter table. Additional columns (as compared with a pristine database schema) in the reporter table in the BASE1.2 schema are not transferred during migration. You have to perform the transfer manually after migration. Simply export the reporter information from BASE1.2, and import the data into the new BASE installation. In BASE1.2: i) View the reporters, ii) Use `Get as tab-separated text` to create a tab separated file (right click and save). In BASE2, to import the file follow the instructions in Section 10.3.1, “Import/update reporter from files”.

  5. Migration done! Happy BASEing.