============================================== Polarion Update 20 R1 Installation Instructions ============================================== This file describes how to update: - To Polarion REQUIREMENTS 20 R1 from all previous versions of Polarion REQUIREMENTS. - To Polarion QA 20 R1 from all previous versions of Polarion QA. - To Polarion ALM 20 R1 from previous versions of Polarion ALM. (Version 3.1.0 or higher.) For multi-instance setup update instructions, see the Polarion Enterprise Setup Guide available on Siemens Doc Center: https://polarion.plm.automation.siemens.com/documentation/latest ----------------------------- IMPORTANT NOTE ---------------------------------- THIS ARCHIVE DOES NOT UPDATE POLARION ALM VERSIONS OLDER THAN VERSION 3.1.0. If you have a Polarion ALM version older than 3.1.0 you need an intermediate update to v. 3.1.0 or later before you can update to the current version. Please get help with such updates at https://polarion.plm.automation.siemens.com/techsupport/resources ------------------------------------------------------------------------------- -------------- 1. TERMINOLOGY -------------- The following substitutions are used in the update instructions below: [INSTALL] means the root directory of your current installation. This would typically be "C:\Polarion" on Windows or "/opt/polarion" on Linux. [UPDATE] means the unpacked Polarion Platform update archive, that is, the directory containing this readme file. [PRODUCT] means the name of the product you are updating - "REQUIREMENTS", "QA", or "ALM". --------------------------- 2. PREPARE FOR THE UPDATE --------------------------- 2.1 Plan for downtime The update procedure itself is fairly quick to accomplish, but a full reindexing of the system is then required. Reindexing begins automatically upon first start of the Polarion server after a successful update installation. Depending on the size of the repository, reindexing can take several hours. End users are not able to use the system during the reindexing process. Therefore, you should plan to perform the update at a time when server access is not critical, possibly consulting your users in advance and alerting them to the planned downtime. Furthermore, note that Polarion will continue to populate the history database even after it is first started, which slows Polarion down until the database is fully populated with existing history data. IF YOU ARE UPDATING A POLARION VERSION PRIOR TO VERSION 2012: Contact Polarion Technical Support ( http://www.siemens.com/gtac ) and request the knowledgebase article "Performance Impact of SQL Layer" before updating your installation to this release. 2.2 Backup It is highly recommended to create a backup copy of all critical data and configuration files before performing the update. Generally it is a good practice to have the valuable resources, namely the Subversion repository, the access and password configuration files, important project builds and Polarion configuration covered by a regular backup routine. 2.3 Required environment a) Since version 2012, Polarion requires significantly more disk space than previous releases. Since version 2012, Polarion makes use of an auxiliary database stored in the data folder. Depending on the size of the repository, the data folder can grow more than 10 times its original size. IMPORTANT! The update script requires that OpenJDK 11 is installed. (Oracle Java SE Development Kit 8 is no longer supported.) Recommendation: Use AdoptOpenJDK 11 (LTS). It is continuously tested with Polarion and offers long-term support. It can be found at: https://adoptopenjdk.net/releases.html?variant=openjdk11&jvmVariant=hotspot b) Before installing OpenJDK 11: 1. Stop the Polarion service. 2. Back up the Java Keystore. (See the "Import a certificate to the keystore" section in the installation guide of your operating system to re-import the certificate after changing to OpenJDK 11.) c) During the OpenJDK installation: While installing or upgrading to OpenJDK 11 make sure the default file encoding matches the same encoding used by the previous version of Java. To make sure that the file encoding is correct: 1. Search for the file.encoding property in the main log file (C:\Polarion\data\logs\main\). 2. If the default file encoding for the new Open JDK 11 differs, then define it explicitly as a Java Runtime property by adding the following property, with the file encoding you deploy, to the polarion.ini file. (C:\Polarion\polarion\polarion.ini by default). Dfile.encoding=file_encoding (Replace "file_encoding" with the one you use.) 3. Reinstall the Polarion service (run service.bat) for the Java Runtime property to take effect. d) After OpenJDK is installed but before installing the update: The JAVA_HOME environment variable must be correctly set. This generally happens automatically when OpenJDK is installed. Another option is to have the directory containing OpenJDK specified in the system PATH variable. You can check it by entering 'java' on the command line. If no such command is found, you must manually configure PATH or reinstall OpenJDK. You can download or view the latest documentation in the Polarion section of Siemens' Doc Center at: https://polarion.plm.automation.siemens.com/documentation/latest 2.4 License key The following points assume you have a current maintenance subscription. a) If you have a license key for the 2015 or 2016 versions of Polarion, you can use your current License Key Code to activate your updated installation. The code has a format like POL-12321-AB34-GFG8767-H86HK. You can activate Polarion online or offline (details in the installation instructions below). Locate your code before starting the update script. b) If you have a license for version 2014 or older, you must obtain a new license key before updating to the current release. You can request a new license online at: https://polarion.plm.automation.siemens.com/getlicense . You should obtain this code before starting the update script. 2.5 Polarion VARIANTS server If you currently have the Polarion VARIANTS Server Add-on installed, download the new Polarion VARIANTS Server Add-on version from https://polarion.plm.automation.siemens.com/downloads/variants and store to an accessible location for installation in the update steps below. 2.6 Changes that may affect your current system Before updating, you should check the Configuration.txt file that's also located in this directory. It contains information about important changes in the current release that may affect your system, including any recommended reconfigurations or installations that should be done before or after you install the update. 2.7 Known issue with PostgreSQL database On some Linux environments, the automatic configuration of PostgreSQL's shared_buffers parameter worked incorrectly , because the calculated value may have exceeded the available shared memory (configured by kernel parameter SHMMAX). In that case, the updater assigns a default value of 24MB for shared_buffers and posts this message: "NOTICE: Polarion attempted to change value of shared_buffers in postgresql.conf to $v_shared_buffers_old but $v_shared_buffers_new was used instead because of low value in /proc/sys/kernel/shmmax." If you see this message during the update, you are advised to review your SHMMAX configuration and adjust shared_buffers for PostgreSQL manually. On Windows environments you must manually update PostgreSQL to the bundled version. ---------------------- 3. UPDATE INSTRUCTIONS ---------------------- 1) Stop the Polarion server and PostgreSQL Service, but keep the Apache service running: On Windows: Run the "Shutdown Polarion Server" and "Shutdown PostgreSQL Service" shortcuts in the [POLARION_HOME]\polarion shortcuts folder. In some installed versions, the Polarion server shortcut may be named "Stop Polarion Server". On Linux: To stop the Polarion server, run as root one of the following commands depending on your distribution: - Common command: [POLARION_HOME]/bin/polarion.init stop - On systems supporting systemd: systemctl stop polarion - On CentOS, RHEL, Debian or Ubuntu: service polarion stop - On SUSE/SLES 11: rcpolarion stop. (And SLES 12 when updating from a version older than 3.10.1) - On SUSE/SLES 12: The Common command. (For all clean installations since 3.10.1) (Stop the PostgreSQL service using the command specific to your Linux distribution.) 2) IMPORTANT: If you have developed your own Polarion plugins (or features) and installed them to [INSTALL]/polarion/plugins(or [INSTALL]/polarion/features), back them up before executing the update script, and add them to the extensions folder after step 3 is complete. See [INSTALL]/polarion/extensions/README.txt. It is created by the update script if it does not exist yet. 3) Run the update script. Windows: Run [UPDATE]\update.bat Linux: Run as root [UPDATE]/update.sh (make it executable first) If the update script fails, please follow the advice given by the script and then run it again. While updating the repository configuration, the update script may print warnings if some of the resources it is trying to add are already found in the repository. If this happens, please open the warnings.txt file (where all warnings are saved), and consider merging these resources manually. You can find the new versions of these files and folders in [PRODUCT]/polarion/install/default-data. You can do this at any time later. 4) For your convenience, check if comments in your users' file: [INSTALL]/polarion/license/users ...are the same as in latest default file: [UPDATE]/[PRODUCT]/polarion/license/users ...and update them if needed. 5) If you have installed the Polarion VARIANTS Server Add-on: a) Delete the existing "purevariants" folder in your Polarion installation file system: [POLARION_HOME]/bundled/purevariants b) Unpack the new Polarion VARIANTS Server Add-on distribution into the same location, following the instructions provided in the README or README.txt file bundled with the add-on distribution. 6) Start the PostgreSQL database: Windows: Start the database using the "Start PostgreSQL Service" shortcut in the folder: [INSTALL]\polarion shortcuts Linux: Run as root one of the following commands depending on your distribution: CentOS/REHL, Debian or Ubuntu: service postgresql-polarion start On SUSE/SLES 11: rcpostgresql-polarion start. (And SLES 12 when updating from a version older than 3.10.1) On SUSE/SLES 12: service postgresql-polarion start. (For all clean installations since 3.10.1) 7) Start the Polarion server: Windows: Start the Polarion server using the "Start Polarion Server" shortcut in the folder: [INSTALL]\polarion shortcuts Linux: Run as root one of the following commands depending on your distribution: Common command: [POLARION_HOME]/bin/polarion.init start OR on systems supporting systemd: systemctl start polarion CentOS/REHL, Debian or Ubuntu: service polarion start On SUSE/SLES 11: rcpolarion start. (And SLES 12 when updating from a version older than 3.10.1) On SUSE/SLES 12: The Common command. (For all clean installations since 3.10.1) Remember that on first startup after installing the update, the reindexeing process launches automatically. The system is not accessible until the reindex process is finished. See section 2.1 above regarding down time. 8) Activate Polarion if needed. When Polarion is up and running, access your Polarion portal in a web browser. If Polarion is not started with a valid license the Activation dialog appears the first time you access the Polarion portal. Enter the License Key Code as discussed in section 2.4 above. If you cannot activate your updated installation online, click "Offline Activation" and follow the steps provided by the Polarion Offline Activation Wizard. 9) Update of third party components Please read Third-party_for_Windows.txt or Third-party_for_Linux.txt in the [UPDATE] folder. If you encounter any problems or need help with update, please get support at https://polarion.plm.automation.siemens.com/techsupport/resources As always, we thank you for using Polarion ALM!