Last modified: October 5,2017

penelope case management software Penelope Upgrade Guide for Upgrading to v4.8.0.1 and v4.8.2.0 For Self-Hosted Clients using Windows

athena software

Athena Software 2

Table of contents

Getting started ......................................................................................................................................... 3About upgrading to v4.8.0.1 or v4.8.2.0 ................................................................................................................ 3Download all required software .............................................................................................................................. 3Steps to Upgrade Penelope .................................................................................................................................. 3

Upgrading Penelope ................................................................................................................................. 4Step 1: Gather configuration data from Penelope .................................................................................................... 4Step 2: Install Java 8 ............................................................................................................................................ 4Step 3: Upgrade to PostgreSQL 9.6 ..................................................................................................................... 4

Back up current PostgreSQL installation .............................................................................................................. 4Stop PostgreSQL and Resin ............................................................................................................................. 4Install PostgreSQL 9.6 ...................................................................................................................................... 4Create the Penelope database in PostgreSQL .................................................................................................... 8

Step 4: Upgrade to Resin 4.0.51 ........................................................................................................................ 10Back up current Resin installation ..................................................................................................................... 10Install Resin 4.0.51 ......................................................................................................................................... 10

Step 5: Set up SSL ........................................................................................................................................... 11Step 6: Configure Resin ..................................................................................................................................... 12Step 7: Install the Penelope software .................................................................................................................... 13Step 8: Start Penelope ....................................................................................................................................... 13

Appendix: resin.properties file ................................................................................................................... 15Legal notice ........................................................................................................................................... 17

Athena Software 3

Getting started

About upgrading to v4.8.0.1 or v4.8.2.0 Upgrading from 4.7.13.3 or lower to Penelope v4.8.0.1 LTS or v4.8.2.0 EDGE or higher requires additional steps to upgrade the underlying infrastructure components. If you are upgrading your Penelope database from v4.8.0.1 or v4.8.2.0 to a newer version, please see the following guide instead: penelopehelp.com/2015/05/15/how-to-apply-a-penelope-upgrade-on-a-windows-server-version-4-0-and-higher/

Download all required software Browse to penelopehelp.com/2016/05/05/penelope-installation-components and download all the required software for the installation:

c Current Penelope software c PostgreSQL 9.6 c Java 8 JDK c Resin 4.0.51 c Resin conf file

Steps to Upgrade Penelope

Gather configuration data from Penelope

Install Java 8

Back up current PostgreSQL installation and upgrade to PostgreSQL 9.6

Install Resin 4.0.51

Set up SSL

Configure Resin

Install the Penelope software

Start Penelope

Athena Software 4

Upgrading Penelope

Step 1: Gather configuration data from Penelope The new configuration of Penelope requires the Attachment Home directory and Penelope External URL be declared inside the resin.properties file. Upon upgrade, Penelope will use the value stored in your database if a value exists. Once a value is declared in the .properties file it will override the current value in the database. As such, we highly recommend that you make note of the paths prior to upgrade.

• Your current Attachment Home directory (available in Penelope > System Admin > Attachments) • Your current Penelope External URL (available in Penelope > System Admin > External Communications)

Step 2: Install Java 8 1. Double-click the Java 8 JDK file you downloaded previously. 2. Accept the default settings (unless you want to change the location where Java 8 is installed).

Step 3: Upgrade to PostgreSQL 9.6

Back up current PostgreSQL installation 1. In Command Prompt, change directory to your PostgreSQL 9.2 bin folder.

cd \<PATH TO POSTGRESQL>\PostgreSQL\9.2\bin

2. Create a backup of the database from the old version of PostgreSQL (9.2) modifying your athenaDB name and the path to store the backup as needed.

pg_dump -U postgres -O -x -Fp athenaDB > \<PATH TO BACKUP>\athenaDBBackup.dmp

3. Enter the PostgreSQL username and/or password when prompted.

Stop PostgreSQL and Resin 1. On your server, browse to Control Panel > Administrative Tools > Services. 2. Right-click the Penelope Resin Service that you’re upgrading and click Stop. 3. Right-click Penelope Postgres Service that you’re upgrading and click Stop.

Install PostgreSQL 9.6 You will need to either stop the older version of PostgreSQL first or set the new version to run on a different port (ie 5434). If you set it to run on a different port any ODBC drivers configurations (used by desktop computers for pivot tables for example) will need to be updated.

Athena Software 5

1. Double-click the PostgreSQL file you downloaded previously. 2. On the Setup – PostgresSQL Welcome page, click Next.

3. In the Installation Directory field, type your preferred installation directory or keep the default location. If

you are installing Postgres 9.6 alongside an older version of PostgreSQL, we recommend that you maintain the default location.

4. Click Next. 5. In the Data Directory field, type your preferred Data Directory or keep the default location. If you are

installing Postgres 9.6 alongside an older version of PostgreSQL, we recommend that you maintain the default location.

Athena Software 6

6. In the Password and Retype password fields, type a password for the postgres admin account in

PostgreSQL.

7. Click Next. 8. In the Port field, type the preferred port number that PostgreSQL will listen on or accept the default. If

you’re installing PostgreSQL 9.6 alongside another version, ensure you use a different port.

Athena Software 7

9. Click Next. 10. From the Locale drop-down, select [Default locale].

Note: By choosing [Default locale], Postgres will take the Locale setting from what is set in the Operation System on the Server.

11. Click Next. 12. The installation is now ready to go to completion. Click Next to proceed.

Athena Software 8

Note: The installation will take several minutes, so please be patient and let the installation run to completion.

13. When prompted to launch Stack Builder, clear the Stack Builder option and click Finish to complete the installation.

4. On your server, browse to Control Panel > Administrative Tools > Services. 5. Right-click the Penelope PostgreSQL Service that you’ve installed and click Start.

Create the Penelope database in PostgreSQL 1. In Command Prompt, connect to psql as the PostgreSQL user modifying your path to PostgreSQL 9.6 and port

(5432) as needed.

<PATH TO POSTGRES>\9.6\bin\psql -p 5432 -U postgres [PRESS ENTER]

Athena Software 9

2. Create the Postgres Roles that exist in your old version in the new one. You will need to know the permissions for each user. We’ve included the commands for some of the typical permissions used with Penelope below though you may have others:

CREATE ROLE pen_db_mask_grp NOLOGIN; [PRESS ENTER] CREATE ROLE pen_db_acces_grp NOLOGIN; [PRESS ENTER] CREATE ROLE athena_dbu LOGIN ENCRYPTED PASSWORD 'YOURPASSWORD'; [PRESS ENTER] CREATE ROLE engage_dbu LOGIN ENCRYPTED PASSWORD 'YOURPASSWORD'; [PRESS ENTER]

3. Create the database.

CREATE DATABASE athenaDB OWNER athena_dbu;

4. Quit psql.

\q

5. Load the backup of your previous database onto the new installation modifying your path to PostgreSQL, the port (5432) if your PostgreSQL 9.6 is running on a different port, and the path to your PostgreSQL 9.2 backup.

<PATH TO POSTGRES>\9.6\bin\pg_restore -p 5432 -U athena_dbu -d athenaDB \<PATH TO BACKUP>\athenaDBBackup.dmp

6. When restoring the backup is complete, Set the permissions for users on the database: a) Connect to psql modifying your path to PostgreSQL and the port (5432) if your PostgreSQL 9.6 is running

on a different port.

<PATH TO POSTGRES>\9.6\bin\psql -p 5432 -U postgres -d athenaDB

b) Enter the following to set user permissions: (Note: you may have more or less users than listed. Modify accordingly.)

REVOKE ALL ON schema public FROM public; [PRESS ENTER] GRANT ALL ON schema public TO athena_dbu; [PRESS ENTER] GRANT USAGE ON schema public TO engage_dbu; [PRESS ENTER] GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO engage_dbu; [PRESS ENTER] GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO engage_dbu; [PRESS ENTER]

7. If your agency uses an ODBC connection, recreate ODBC users setup on your system and give them the same permissions as previously used prior to upgrading.

8. Quit psql.

\q

9. Copy the pg_hba.conf file from the original PostgreSQL data directory into the new PostgreSQL data directory.

Athena Software 10

Step 4: Upgrade to Resin 4.0.51

Back up current Resin installation 1. Make a copy of your current Penelope Resin folder using a similar command modifying the path to and name of

your Resin directory as needed.

cd <PATH TO RESIN>\..; cp -r resin-4.0.40 resin-copy-20170717;

Note: If your Penelope Resin directory contains the keystore file (declared as jsse_keystore_file in resin.properties), move it to a directory called keys outside of the Penelope Resin directory. If a keystore does not yet exist, one will need to be created as it is now required in order to run Penelope.

Install Resin 4.0.51 1. Unzip the resin-4.0.51.zip file that you downloaded previously to its own directory (for example, ~\resin\resin-

4.0.51-penelope). 2. In the resin-4.0.51-penelope directory, rename the conf folder to conf-dist. 3. Unzip the previously downloaded Resin conf directory into the resin-4.0.51-penelope directory. 4. In the resin-4.0.51-penelope directory, double-click the Setup.exe file.

Note: If an error message appears when you double-click the Setup.exe file indicating you need to install .NET 3.5 to the Resin setup.exe command, you can install .NET 3.5 via the PowerShell on Windows:

The following display appears:

Athena Software 11

5. Based on the display show above, configure the following fields (all other fields can be left at their default settings): a. In the Java Home field, type the path for the Java 8 version you’re going to use. Do not leave Default as

the value. b. In the Service Name field, type a name that identifies the purpose of this Resin and matches the name of

the Resin directory. For example, Resin4-Prod or Resin4-Test. c. In the Service User field, select one of the following options:

i. To run Resin under Local Service, leave the default setting of Local Service. ii. To run Resin under a specific account, from the drop-down, select the account you want to use.

6. Click Install/Change. 7. When the installation is complete, the display Resin Setup screen remains active. Close the window.

Step 5: Set up SSL Penelope v4.8.0.0 and higher requires the use of SSL encryption (i.e. Penelope must be accessed using the https:// version of your URL instead of the http:// version). An SSL certificate is typically obtained through your web hosting provider although there are many variations in their provision. Once you have your SSL certificate, complete the steps in the Set up SSL in Resin guide at penelopehelp.com/2016/08/25/set-up-ssl-in-resin/.

Athena Software 12

Step 6: Configure Resin Please refer to the Appendix: Resin.properties file topic for more information about each of the properties in the resin.properties file.

1. Browse to the \resin-4.0.51-penelope\conf directory. 2. Rename the resin.properties.dist file to resin.properties. 3. Open the resin.properties file. 4. Change the highlighted/bolded parameters below and, if necessary, remove the prepending # (comment) symbol:

Note: When changing the Ports listed below in the resin.properties file, ensure that you use the same ports as in your pre-4.8 resin.properties file.

### ---------- config version 1.0.0.1 ------------ # Penelope's external address (including port) and the entailing slash. Example: https://www.companyPenelope.com:5050/ pen_external_url : ***CHANGE ME*** # Ports. #https : 443 ***CHANGE ME*** #hmux_port : 6800 ***CHANGE ME*** #watchdog_port : 6600 ***CHANGE ME*** # Set the timezone. Example: America/New_York timezone : ***CHANGE ME*** # Attachment home directory. # This should be changed to match the Penelope attachment location (previously set in Penelope > System Admin > Attachements). # First time Penelope setup. Default: /attachments/ #pen_attachment_dir : ***CHANGE ME*** # JSSE certificate configuration # Keys are typically stored in the resin configuration directory. jsse_keystore_type : jks jsse_keystore_file : ***CHANGE ME*** jsse_keystore_password : ***CHANGE ME*** # OpenSSL certificate configuration (Resin Pro only). # Keys are typically stored in the resin configuration directory. # openssl_file : /path/to/gryffindor.crt # openssl_key : /path/to/gryffindor.key # openssl_password : # Database Properties. driver_url : jdbc:PostgreSQL://localhost:5432/athenadb db_user : penelope_dbu db_password : ***CHANGE ME*** # How often Resin should check for updated files. # Configures how often the environment context should be checked for changes. dependency_check_interval : 600s # Pass more JVM arguments if necessary. jvm_args : -Xmx386m prepared_statement_cache_size : 8 max_connections : 20 max_idle_time : 30s connection_wait_time : 3s

Athena Software 13

# Enabling WebAppMXBean. statistics_enable : true # Configures the minimum free memory allowed before Resin will force a restart. memory_free_min : 1m # Enables/disables exceptions when the browser closes a connection. ignore_client_disconnect : true # Document directory path. document_directory_path : webapps/AthenaCaseManagement # Specify the user name and group name for the web server user on a non-Windows environment. #setuid_user : #setuid_group :

5. Save your changes.

Step 7: Install the Penelope software 1. Unzip the Penelope Software file that you downloaded previously. 2. When prompted, type in the password you received from the Athena Technical Support Team. 3. If your version of Windows creates an encrypted AthenaCaseManagement folder, complete the following actions to

unencrypt the folder: a. Right-click the folder and click Settings. b. Click the Advanced option. c. Clear the “Encrypt contents to secure data option. d. Click Apply. e. When prompted to apply changes to the folder, subfolder and files, leave this option selected and click

OK. 4. Once the folder has been completely extracted (and unencrypted if required), copy the folder to the \resin-

4.0.51\webapps folder.

Step 8: Start Penelope 1. On your server, browse to Control Panel > Administrative Tools > Services. 2. Right-click the Penelope Resin Service that you’re upgrading and click Start. 3. To verify that Resin started successfully, in a browser, enter your Penelope external URL.

If installed correctly, you should see the Penelope login screen shown below:

Athena Software 14

Athena Software 15

Appendix: resin.properties file Property Description

pen_external_url Your Penelope external URL.

https Penelope’s secure port. You must ensure that all of the ports used on your server are unique. This port most often needs to be changed as it may conflict if you have another Web Apps server running on your server. If any of the ports are already in use, Resin will not start.

hmux_port This port only needs to be changed if you are running more than one instance of Resin (i.e. if you have a Penelope sandbox) on your server.

watchdog_port This port only need to be changed if you are running more than one instance of Resin (i.e. if you have a Penelope sandbox) on your server.

timezone Your Penelope database time zone.

pen_attachment_dir The path to your Penelope attachment directory.

jsse_keystore_type The JSSE keystore type.

jsse_keystore_file The path to your SSL keystore file. For example, C:\Program Files\Athena\keys\athena.keystore

jsse_keystore_password The password to decrypt the jsse_keystore_file

openssl_file The OpenSSL certificate configuration. Note that this is applicable to Resin Pro only which is not supported for use with Penelope. openssl_key

openssl_password

driver_url If you changed the default port (5432) during the PostgreSQL installation, ensure you change the port here (for example, jdbc:PostgreSQL://localhost:5434/athenadb).

db_user

The PostgreSQL account you created for access to your database. For example, penelope_dbu.

db_password The password for the PostgreSQL account you created for access to your database.

dependency_check_interval How often Resin should check for updated files.

jvm_args Additional arguments passed through to the Java Virtual Machine.

prepared_statement_cache_size Configures how many prepared statements Resin should cache for each connection.

Athena Software 16

max_connections The maximum number of connections to the database for the connection pool.

max_idle_time Configures the maximum time a connection to the database can remain idle before Resin automatically closes it.

connection_wait_time Configures the time a connection call should wait when then pool is full before trying to create an overflow connection.

statistics_enabled Enabling WebAppMXBean.

memory_free_min Configures the minimum free memory allowed before Resin will force a restart.

ignore_client_disconnect Enables or disables exceptions when the browser closes a connection.

document_directory_path The document directory path to the AthenaCaseManagement folder.

setuid_user Only applicable to non-Windows environments.

setuid_group Only applicable to non-Windows environments.

Athena Software 17

Legal notice © 2017 Athena Software. All rights reserved. The information in this document is provided "AS IS" and without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. This information could contain technical inaccuracies or typographical errors. Changes may be made periodically to the information herein without notice. This document may contain links or references to products, materials or web sites that are provided by independent third parties either directly or through frames. The availability of such third-party material does not constitute any form of recommendation, endorsement or publication of such third-party material by us. Any concerns that you have about the third-party material should be directed to the relevant third party. iPhone®, iPad®, and Safari® are trademarks of Apple Inc. Chrome™, Google™ and Gmail™ are trademarks of Google Inc. Active Directory®, Excel®, Internet Explorer®, Microsoft®, and Office 365 are trademarks of Microsoft Corporation. Firefox® and Mozilla® are trademarks of The Mozilla Foundation. Other company and product names mentioned herein may be trademarks of their respective companies.