Columbus 2.5. Installation Guide

Transcription

1 Columbus 2.5 Installation Guide Last Updated: September 3, 2014

2 Table of Contents 1 Introduction General Prerequisites Columbus 2.5 Installation on SLES Prerequisites Installation from Online Repository Installation from DVD or Folder Customized Installation Locations Upgrading from Previous Columbus 2.5 versions on SLES Upgrading from Columbus 2.3 to 2.4 on SLES Database Migration Columbus Software Upgrade Columbus 2.5 installation on RHEL Prerequisites Installation from Online Repository Installation from DVD Upgrading from previous Columbus 2.5 versions on RHEL Upgrading from Columbus 2.3 to 2.4 on RHEL Creating Database Dump Mounting File Repository on New RHEL 6 System Installing Columbus 2.5 Software Migrating the Database Starting the Server General Notes First-time Sign In Vendor Changes or Conflicting Packages Repository Administration SLES Refreshing Repository before Upgrade Repository Administration RHEL Creating a Database Dump Copyright PerkinElmer, Inc. All rights reserved. 2 of 15

3 10.7 Temporary Files Adding Swap Files to Increase Available Swap Space Tomcat Webservice Configuration Enable SSL/TLS for Columbus Login Page Troubleshooting Database Migration Copyright PerkinElmer, Inc. All rights reserved. 3 of 15

4 1 Introduction Columbus is distributed as a bundle of RPM packages for SUSE Linux Enterprise 11 (SLES 11) and Red Hat Enterprise Linux 6 (RHEL 6). The packages are available from an online software repository or a DVD. The installation of these packages differs between operating systems where the prerequisites and procedures are described below. 1.1 General Prerequisites The system hardware must conform to the Columbus Hardware Specification. Administrator privileges are required for the installation process and it is recommended to have network access on the system, setup with a static IP address and the hostname registered in local DNS. If an additional storage system is to be used for the file repository, it must be mounted and the path must be known. The firewall between client computers and the Columbus server must allow TCP traffic on ports: 22 (ssh for administrator access), 80, 443 (http, https Columbus webapp), 4063, 4064 (Columbus Java clients), and 8081 (http Columbus SOAP webservice interface). The system must have at least 64GB of swap file space. See the section on checking and adding swap files later in this guide to meet this requirement. 2 Columbus 2.5 Installation on SLES Prerequisites The package manager program zypper must be setup so the operating system installation media (DVD or online repository) are available and enabled. To configure this, check the software repository settings under the software management section in YaST. In addition to the standard repositories, the SUSE Linux Enterprise Software Development Kit (SDK) 11 must be available. Usually this is done by adding the SDK ISO image as an 'Add-On' product under the software management section in YaST. Details can be found in the SLES 11 Deployment Guide. 2.2 Installation from Online Repository You need to add the Columbus software online repository to the available software repositories. Once it is available, you can install the 'Columbus' package. To perform the installation from the command line, you issue the following commands. Note: All commands are on one line. Sometimes this is illustrated with a \ at the end of the first line. user@columbus-server:~> sudo zypper addrepo f \ Columbus user@columbus-server:~> sudo zypper install Columbus The last command may require confirmation to store software-sign-keys and some installation steps. For details see the zypper manual page. It is also possible to add the repository and install Columbus using YaST, see SLES 11 Deployment Guide for details. Once installed, start Columbus by following the section entitled Starting the Server. Copyright PerkinElmer, Inc. All rights reserved. 4 of 15

5 2.3 Installation from DVD or Folder Similar to the installation from an online repository, you need to add the installation folder on the DVD as a software repository. Once the DVD is mounted, you enter the following commands on the command line to perform the installation. Note: The path to the DVD drive may vary. To update the path to the DVD drive use the following command: user@columbus-server:~> sudo zypper addrepo f \ /media/cdrom/installation/server/sles11.1 Columbus user@columbus-server:~> sudo zypper install Columbus The last command may require confirmation to store software-sign-keys and installation steps. For details see the zypper manual page. It is also possible to add the repository and install Columbus using YaST, see SLES 11 Deployment Guide for details. In case you have downloaded a zip archive containing the software packages, the process is similar except that you use the path to the unzipped archive. Once installed, start Columbus by following the section entitled Starting the Server. 3 Customized Installation Locations In case a different data repository should be used, the default is /OMERO/OMERO4_4, you can set an environment variable that points to the new location before you run the installation. We recommend using the default value for the last components of the path. user@columbus-server:~> sudo su - user@columbus-server:~> DATA_DIR=/path/to/data/repository/OMERO/OMERO4_4 \ zypper install Columbus Another option is to use the default but create a link that points to the actual repository location before you run the installation. user@columbus-server:~> sudo ln -s /path/to/data/repository/omero /OMERO user@columbus-server:~> sudo zypper install Columbus The default installation folder is /usr/local/perkinelmerctg. In order to change the software installation folder, we recommend creating a link that points to the customized location before you install the software. user@columbus-server:~> sudo ln -s /path/to/software/installation/folder \ /usr/local/perkinelmerctg 4 Upgrading from Previous Columbus 2.5 versions on SLES 11 Note: Before you perform an upgrade, we recommend to create a backup of your file-repository. At least you must make sure to have a recent database dump. See the General Notes section for details. Before you perform an upgrade make sure that your Columbus SMA expiration date has not passed. Copyright PerkinElmer, Inc. All rights reserved. 5 of 15

6 Make sure that your registered Columbus software repository points to the location of the new Columbus 2.5 software. You can get the list of currently registered software repositories using zypper: sudo zypper lr u Check that the URL of the Columbus software repository either points to the online repository mentioned in the installation section or to the software repository on the DVD as described above. In case the registered repository differs from the one where the new Columbus 2.5 software is located, remove the existing repository: user@columbus-server:~> sudo zypper rr Columbus Afterwards, register the new repository as described in the installation section. Manually stop the current Columbus server and run the update with the following commands: user@columbus-server:~> sudo /etc/init.d/columbus stop user@columbus-server:~> sudo zypper update r Columbus Where the last argument of the second command is the repository name you specified when the Columbus software repository was registered. Once the upgrade completed, start Columbus by following the section entitled Starting the Server. 5 Upgrading from Columbus 2.3 to 2.4 on SLES 11 Note: Before you perform an upgrade of Columbus, we recommend: Creating a backup of your file-repository which should also contain an up-to-date database dump. Ensuring your Columbus SMA has not expired. The Columbus upgrade is a two-step process: 1. Database migration 2. Columbus software upgrade These steps are detailed below. 5.1 Database Migration The database migration is performed with a shell script that needs to be run from the command line of the Columbus server. This script is available on the DVD and in the online repository. Depending on the database size and server system, the migration can take a significant time, up to several hours. Hence, when using a remote SSH connection to run the script on the Columbus server, it is recommended to run it within a screen-session as described below, otherwise the script will be terminated if the connection is accidentally lost. Note: Alternatively, you can use the nohup command. See the manual pages of nohup for details. Enter the following commands to download the script from the online repository and make it executable: user@columbus-server:~> wget \ lumbus_db_migration.sh Copyright PerkinElmer, Inc. All rights reserved. 6 of 15

7 chmod a+x columbus_db_migration.sh To use the script from the DVD, copy it to your working folder: cp \ /media/cdrom/server/installation/sles11.1/columbus_db_migration.sh. Once the script is in place, start a screen-session and run the script with administrator privileges: user@columbus-server:~> screen user@columbus-server:~> sudo./columbus_db_migration.sh Note: If you lose connection to the server, create a new one with the following command. user@columbus-server:~> screen r When executing, the migration script does the following: Displays an estimate for the total run length. Creates a new database dump in the /OMERO/OMERO4_1/db_backup folder. Restores this dump into a new database instance. Performs the database migration on the new database. Note: The progress reporting feedback may not update for a period of time, this does not mean the process has stopped working. If you require information on the database migration, a detailed log may be found in the file 2.3-to-2.4-dbmigration.log located in the current working folder. Any changes made in Columbus 2.3 after the migration script has been run will not be part of the migrated Columbus 2.4 database. 5.2 Columbus Software Upgrade Once the database migration has been completed, the next step is to upgrade from Columbus 2.3 to Columbus 2.4. Remove the old Columbus repository by typing the following command: user@columbus-server:~> sudo zypper rr Columbus Add the new Columbus 2.4 repository as follows: user@columbus-server:~> sudo zypper addrepo \ Columbus Manually stop the Columbus server and remove the Acapella RPMs with the following commands: user@columbus-server:~> sudo /etc/init.d/columbus stop user@columbus-server:~> sudo rpm e -nodeps Acapella2.7 Acapella2.7-server The update can then be performed with the following command: user@columbus-server:~> sudo zypper update r Columbus Copyright PerkinElmer, Inc. All rights reserved. 7 of 15

8 After the update has completed successfully, start Columbus by following the section entitled Starting the Server. 6 Columbus 2.5 installation on RHEL Prerequisites The package manager program yum must be setup so the operating system installation media (DVD or URL) are available and enabled. See the Package Management Manual for details. 6.2 Installation from Online Repository You need to add the Columbus software online repository to the available software repositories. Once the software repository has been set up, you can install the 'Columbus' package. The following command installs the required repository registration file. Note: You need to run yum install yum-utils in case yum-config-manager is not installed. user@columbus-server:~> sudo yum-config-manager -add-repo \ user@columbus-server:~> sudo yum --nogpgcheck install Columbus Once installed, start Columbus by following the section entitled Starting the Server. 6.3 Installation from DVD Similar to the installation from an online repository, you needs to add the installation folder on the DVD as a software repository. There is an RPM package on the DVD that registers the DVD as a software repository. Once the DVD is mounted, enter the following commands on the command line to perform the installation. Note: The path to the DVD drive may vary. To update the path to the DVD drive use the following command: user@columbus-server:~> sudo yum-config-manager -add-repo \ file:///media/cdrom/installation/server/rhel6 user@columbus-server:~> sudo yum --nogpgcheck install Columbus If you have downloaded a zip archive containing the software packages, the process is similar except that you use the path to the unzipped archive. Once installed, start Columbus by following the section entitled Starting the Server. 7 Upgrading from previous Columbus 2.5 versions on RHEL 6 Note: Before you perform an upgrade of Columbus, we recommend: Creating a backup of your file-repository which should also contain an up-to-date database dump. Ensuring your Columbus SMA has not expired. Make sure your registered Columbus software repository points to the location of the new Columbus 2.5 software. Copyright PerkinElmer, Inc. All rights reserved. 8 of 15

9 You can get the list of currently registered software repositories using yum: sudo yum repolist -v Check that the URL of the Columbus software repository either points to the online repository mentioned in the installation section or to the software repository on the DVD as described above. In case the registered repository differs from the one where the new Columbus 2.5 software is located, either remove the existing repository and register the new repository as described in the installation section above, or modify the /etc/yum.repos.d/columbus2.5.repo manually. Once the repository is setup, manually stop the current Columbus server and run the update with the following commands: sudo /etc/init.d/columbus stop yum groupupdate Columbus After the update has completed successfully, start Columbus by following the section entitled Starting the Server. 8 Upgrading from Columbus 2.3 to 2.4 on RHEL 6 Note: Before you perform an upgrade of Columbus, we recommend: Creating a backup of your file-repository which should also contain an up-to-date database dump. Ensuring your Columbus SMA has not expired Columbus 2.4 is only supported on RHEL 6. This means that for an upgrade from Columbus 2.3 (RHEL 5), a change to RHEL 6 will be required. Alternatively, Columbus may be moved to a new server with RHEL 6. Note: RHEL 6 must be a fresh installation as Red Hat do not support upgrades from earlier major versions. In either case, the Columbus upgrade is a four-step process: 1. Create database dump on existing RHEL 5 system 2. Mount file repository on new RHEL 6 system 3. Columbus 2.4 software installation 4. Database migration These steps are detailed below. 8.1 Creating Database Dump Stop Columbus and create a database dump on the existing Columbus 2.3 installation on RHEL 5, the dump file needs to be stored in the db_backup folder in the Columbus file repository: columbus@columbus-server:~> sudo /etc/init.d/columbus stop columbus@columbus-server:~> sudo su columbus - columbus@columbus-server:~> pg_dump Fc v f \ /OMERO/OMERO4_1/db_backup/omero4_1_dump_before_upgrade.pg_dump omero4_1 columbus@columbus-server:~> exit Copyright PerkinElmer, Inc. All rights reserved. 9 of 15

10 8.2 Mounting File Repository on New RHEL 6 System Once the database dump is created, either perform a fresh installation of RHEL 6 on the same system or move the file repository to a new server where RHEL 6 has been installed. After the file repository is available again under the new operating system, rename the OMERO4_1 folder to OMERO4_4 so that the new software installation recognizes it: user@columbus-server:~> sudo mv /OMERO/OMERO4_1 /OMERO/OMERO4_4 8.3 Installing Columbus 2.5 Software After the file repository name has been changed, you need to perform a standard Columbus 2.5 software installation as described in the Columbus 2.5 installation on RHEL 6 section above. Once the installation is complete, check that the files and folders inside the file repository are owned by the Columbus user, and if this is not the case, perform an ownership change: columbus@columbus-server:~> sudo chown R columbus: /OMERO/OMERO4_4 Do not start Columbus after installation. You must first perform the database migration as described in the next section. If Columbus 2.3 was not running with a default license file, then you need to copy that file from the RHEL 5 system to the RHEL 6 system to /etc/acapella_license.txt. 8.4 Migrating the Database The aim of this step is to replace the empty default database from the installation with the Columbus 2.3 database dump you have created in the first step. The database migration is performed with a shell script that needs to be run from the command line of the Columbus server. This script is available on the DVD and in the online repository. Depending on the database size and server system, the migration can take a significant time, up to several hours. Hence, when using a remote SSH connection to run the script on the Columbus server, it is recommended to run it within a screen-session as described below, otherwise the script will be terminated if the connection is accidentally lost. Note: Alternatively, you can use the nohup command. See the manual pages of nohup for details. Enter the following commands to download the script from the online repository and make it executable: user@columbus-server:~> wget \ bus_db_migration.sh user@columbus-server:~> chmod a+x columbus_db_migration.sh To use the script from the DVD, copy it to your working folder: user@columbus-server:~> cp \ /media/cdrom/server/installation/rhel6/columbus_db_migration.sh. Once the script is in place, start a screen-session, drop the empty database and run the script with administrator privileges, as an argument you supply the path to the database dump file that you have created above: Copyright PerkinElmer, Inc. All rights reserved. 10 of 15

11 screen sudo su - postgres user@columbus-server:~> dropdb omero4_4 user@columbus-server:~> exit user@columbus-server:~> sudo./columbus_db_migration.sh \ /OMERO/OMERO4_4/db_backup/omero4_1_dump_before_upgrade.pg_dump Note: If you lose connection to the server, create a new one with the following command: user@columbus-server:~> screen r When running, the migration script does the following: Displays an estimate for the total run length. Restores this dump into a new database instance. Performs the database migration on the new database. Notes: The progress reporting feedback may not update for a period of time, this does not mean the process has stopped working. If you require information on the database migration, a detailed log may be found in the file 2.3-to-2.4-dbmigration.log located in the current working folder. After the database migration has completed successfully, start Columbus by following the section entitled Starting the Server. 9 Starting the Server The Columbus server can be started manually by calling: user@columbus-server:~> sudo /etc/init.d/columbus start The service script is invoked automatically during system start. The server applications run under the Columbus and Acapella system accounts. The status of the server can be checked with: user@columbus-server:~> sudo /etc/init.d/columbus status The server can be stopped with: user@columbus-server:~> sudo /etc/init.d/columbus stop The additional web-service application which is used by third-party applications to access the Columbus database needs Tomcat running. To start Tomcat: user@columbus-server:~> sudo /etc/init.d/tomcat6 start Copyright PerkinElmer, Inc. All rights reserved. 11 of 15

12 10 General Notes 10.1 First-time Sign In With a browser on a client machine, navigate to and sign in with the default administrator credentials (username: root and password: columbus). Use the Users & Groups link from the Administration menu to open the user and group administration panel. Here you can create a new group and new user to start working with Columbus with these new accounts Vendor Changes or Conflicting Packages The installation process may complain about vendor changes of packages, this should be accepted. In case of conflicting packages, try to choose a solution that keeps the most recent version of the package. For instance, the aksusbd package may be installed in an older version and the installation process will report a conflict with the new version included in Columbus Repository Administration SLES11.1 To list all software repositories, you can use the list-repository command user@columbus-server:~> sudo zypper lr To remove a software repository, e.g. an invalid Columbus repository, you can use the name (in this example Columbus ) of the repository and the remove-repository command: user@columbus-server:~> sudo zypper rr Columbus 10.4 Refreshing Repository before Upgrade On SLES 11, in case the Columbus repository is not set to be refreshed automatically, the update command may not find any update packages for Columbus. In this case you need to refresh the repository manually, here the repository is name Columbus : user@columbus-server:~> sudo zypper refresh Columbus 10.5 Repository Administration RHEL 6 To list all software repositories, you can use the repolist command user@columbus-server:~> sudo yum repolist To remove the Columbus software repository, remove the Columbus repository file in /etc/yum.repos.d. Depending on how the repository was registered, the file name can vary Creating a Database Dump For a backup of the relational database tables, you can create a database dump and store it in a secure backup location. Columbus installs a cronjob that creates a database dump in the file repository under the db_backup folder. In order to perform a dump manually before an update you can run the following commands. Copyright PerkinElmer, Inc. All rights reserved. 12 of 15

13 Note: The path to the Columbus file repository may vary. sudo /etc/init.d/columbus stop sudo su columbus pg_dump Fc v f \ /OMERO/OMERO4_4/db_backup/omero4_4_dump_before_upgrade.pg_dump omero4_ Temporary Files The Columbus system may create large temporary files. These are stored in /tmp for which we recommend at least 20GB of free space, and in /var/lib/acapella which allow to keep at least 4GB of data Adding Swap Files to Increase Available Swap Space On many systems, the default swap size can be too low for Columbus to run effectively. It is recommended that the system have at least 64GB swap space. This can be achieved by adding additional swap files manually to the system. This process needs to be done one-time only and will not need to be repeated for upgrades. Start by checking the amount of swap space available on the system using the command: user@columbus-server:~> cat /proc/swaps The output will be something like: Filename Type Size Used Priority /dev/sda1 partition The size parameter is in kbytes and indicates that this system has the default 2GB swap space available. To add additional swap space run the following commands: user@columbus-server:~> sudo mkdir -p /var/lib/swap user@columbus-server:~> sudo dd if=/dev/zero of=/var/lib/swap/swapfile \ bs=1m count=65536 Note: The above command creates a 64GB swap file and can take up to 40 minutes to complete. Once the file is created, it can be activated by using the command: user@columbus-server:~> sudo mkswap /var/lib/swap/swapfile user@columbus-server:~> sudo swapon /var/lib/swap/swapfile Now listing the active swap files with: user@columbus-server:~> cat /proc/swaps looks as follows: Filename Type Size Used Priority Copyright PerkinElmer, Inc. All rights reserved. 13 of 15

14 /dev/sda1 partition /var/lib/swap/swapfile file To make the change permanent, the /etc/fstab file must be modified to instruct the system to load the additional swap file at boot automatically. To make this change, you have to add the following line to the /etc/fstab file: /var/lib/swap/swapfile swap swap defaults Tomcat Webservice Configuration An increased maximum memory assignment for Tomcat is recommended. This can be achieved by modifying the CATALINA_OPTIONS variable in /etc/sysconfig/tomcat6, e.g. add "-Xmx2048M" to this variable in order to set the maximum memory usage to 2GB Enable SSL/TLS for Columbus Login Page Columbus can be configured to serve the Columbus login page over https which uses SSL/TLS to encrypt the user authorization data. In order to enable https perform the following steps: 1. Stop Columbus 2. Edit the file /etc/init.d/columbus and remove the comment in front of the line which contains the variable COLUMBUS_ENABLE_HTTPS 3. Start Columbus again With this configuration change, users visiting will be redirected to Note that the changes to /etc/init.d/columbus will be overwritten with an update of the Columbus software. The first time this page is loaded, you will get a warning that the security certificate used by this page cannot be trusted. This is because Columbus ships with a self-signed certificate which is not in a trusted authority list. You can ignore the warning and the browser will show a symbol in the UI that the page is not trustworthy. In order to avoid this warning you can either install the certificate into the clients certificate store or replace the certificate and security key on the Columbus system which are stored in /usr/local/perkinelmerctg/columbus2.5/webapp/server/config with officially signed versions. 11 Troubleshooting If the Columbus server application does not work properly and you cannot log into the Columbus web application, you should check the log files in /var/log/columbus. There are three folders for each of the components of the system, each with a couple of log files. If the database is not running, check the content of the files master.err and _Blitz-0.log in the /var/log/columbus/db/ folder. If the Acapella server is not running, check the content of the file /var/log/columbus/acc/acapella.log If the web server is not running, check the content of the files /var/log/columbus/web/columbus.log and /var/log/columbus/nginx/error.log. When contacting the support team for assistance it may be helpful to send a zipped version of the log files with your request. The following command will create a logs.zip archive that contains all the log files from the /var/log/columbus folder. Copyright PerkinElmer, Inc. All rights reserved. 14 of 15

15 zip -r logs.zip /var/log/columbus 11.1 Database Migration In case of a database migration failure, the following commands will drop the newly created omero4_4 database. Caution: Only run these commands when you are certain you want to delete the database. user@columbus-server:~> sudo su postgres postgres@columbus-server:~> dropdb omero4_4 postgres@columbus-server:~> exit Copyright PerkinElmer, Inc. All rights reserved. 15 of 15