Chesar 3 installation manual : server (i.e. ‘distributed’) version.
Date: 2016-08-10
Institutions: European Chemicals Agency
Subjects: European Chemicals Agency, administrative formalities, chemical product, software, user guide

13/06/2016 

Chesar 3 installation manual 

Server (i.e. ‘distributed’) version 

Annankatu 18, P.O. Box 400, FI-00121 Helsinki, Finland | Tel. +358 9 686180 | Fax +358 9 68618210 | echa.europa.eu 

 
 
 
 
 
 
 
 
Disclaimer 
The  information  contained  in  this  manual  does  not  constitute  legal  advice.  The  European 
Chemicals  Agency does  not  accept  any  liability  with  regard  to  the  contents  of this  document. 
The European Chemicals Agency is entitled to modify or revise the document at any time with 
or without notice and with or without cause.  

Chesar 3 installation manual  
Server version  

ECHA ref: ECHA-16-B-22-EN 

ISBN: 978-92-9495-153-3 

Catalogue number: ED-01-16-598-EN-N 

DOI: 10.2823/58420 

Publication date: June 2016  

Language: EN  

© European Chemicals Agency, 2016  

Cover page © European Chemicals Agency  

Reproduction is authorised provided the source is fully acknowledged in the form  
“Source:  European  Chemicals  Agency,  http://echa.europa.eu/”,  and  provided  written 
notification is given to the ECHA Communication Unit (publications@echa.europa.eu). 

ECHA  invites  interested  parties  to  submit  comments  on  this  document  which  may  be 
incorporated  in  future  updates.  These  can  be  submitted  via  the  Contact  ECHA  page  at: 
http://echa.europa.eu/about/contact_en.asp 

European Chemicals Agency  

Mailing address: P.O. Box 400, FI-00121 Helsinki, Finland  
Visiting address: Annankatu 18, Helsinki, Finland 

13/06/2016 13:32 

2 (20) 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
Contents 

1. INTRODUCTION ......................................................................................................................................... 4 

2. PREREQUISITES ........................................................................................................................................ 4 

2.1. HARDWARE REQUIREMENTS ................................................................................................................................. 4 
2.2. SOFTWARE REQUIREMENTS .................................................................................................................................. 4 
2.3. SECURITY .............................................................................................................................................................. 5 

3. INSTALL CHESAR 3 SERVER VERSION ............................................................................................ 5 

3.1. SET UP DATABASE SERVER ................................................................................................................................... 5 
3.1.1. Set up Derby Network Server (Java DB Server) ........................................................................ 5 
3.1.2. Set up Oracle Database ........................................................................................................................ 7 
3.2. MIGRATE FROM CHESAR 2.3 DATABASE TO CHESAR 3 DATABASE .................................................................. 7 
3.3. SET UP APPLICATION SERVER (OR SERVLET CONTAINER) ................................................................................. 7 
3.3.1. Set up Tomcat .......................................................................................................................................... 8 
3.3.2. Set up Glassfish ....................................................................................................................................... 8 
3.4. DEPLOY CHESAR 3 ............................................................................................................................................... 8 

4. MIGRATE CHESAR 2.3 TO CHESAR 3 .............................................................................................. 10 

4.1. DOWNLOAD AND INSTALL THE CHESAR 2.3 TO CHESAR 3 MIGRATION TOOL .............................................. 10 
4.2. CHECKS TO DO BEFORE RUNNING THE MIGRATION TOOL ................................................................................ 10 
4.3. RUN THE MIGRATION TOOL ................................................................................................................................ 10 

5. ACCESS CHESAR 3 .................................................................................................................................. 13 

6. REGULAR BACKUPS ................................................................................................................................ 13 

7. REPORTING ISSUES ............................................................................................................................... 14 

8. ANNEXES ..................................................................................................................................................... 14 

8.1. ANNEX: INSTALL DERBY NETWORK SERVER.................................................................................................... 14 
8.2. ANNEX: INSTALL TOMCAT ................................................................................................................................. 15 

13/06/2016 13:32 

3 (20) 

 
 
 
 
 
 
 
1. Introduction 

Thank you for choosing to install the Chesar 3 application. Chesar is an application developed 
by the European Chemicals Agency (ECHA) to help companies carry out their chemical safety 
assessments (CSAs) and prepare their chemical safety reports (CSRs) and exposure scenarios 
(ES) for communication in the supply chain. 

This document will guide you through the steps required to install and configure Chesar 3 
server version, and covers 2 situations: 

•  You do not have any version of Chesar installed, and you want to install Chesar 3. 
•  You already have Chesar v2.3 installed, and you want to upgrade to Chesar 3. 

If you have any other situation, please contact our helpdesk: 

http://echa.europa.eu/contact/helpdesk-contact-form 

  Please  note  that  the  installation  of  Chesar  3  server  version  requires  a  high  degree  of  IT 

technical expertise. We recommend that this setup is performed by IT service personnel.  

This  guide  provides  some  quick-start  descriptions  on  how  to  perform  the  technical 
configurations.  These  instructions  should  not  be  seen  as  a  substitute  for  any  of  the  official 
documentation  including  administration  guides  which  can  be  found  on  the  Oracle,  Glassfish, 
Tomcat and Derby product websites. 

2. Prerequisites 

If  you  have  Chesar  2.3  data,  please  make  sure  that  all  your  data  is  safely  backed  up. 
After you have backed-up your data, you will need to migrate the data using the migration tool 
(see section 4: Migrate Chesar 2.3 to Chesar 3). 

 In case you are one of the companies that assisted ECHA in performing testing/evaluation 
of  beta  versions  of  the  Chesar  and  migration  tool  software,  please  remember  that  you  must 
not  reuse any of the data that you generated during this beta testing, in this new version of 
Chesar. This might corrupt your Chesar data. 

2.1. Hardware requirements 

Minimum hardware recommendations for a server installation with 2 to 10 simultaneous users 
and less than 500 substances: 

Application server 

Database server 

Network 

Characteristics 
CPU/Cores 
Memory 
CPU/Cores 
Memory 
Topology/Firewall/Proxy 

Client machine (with browser)  CPU/Cores 

Memory 

2.2. Software requirements 

Value 
Dual Core/ 3.0 GHz 
4 GB 
Dual Core/ 3.0 GHz 
4 GB 
Connection between database 
and application server 
(Gigabit wired) 
Dual Core/ 2.0 GHz 
4 GB 

Before installing Chesar 3 server software package you must first install Java, a database 

13/06/2016 13:32 

4 (20) 

 
 
 
 
 
 
 
 
 
 
server (e.g. Derby Network Server or Oracle) and an application server (e.g. Tomcat or 
Glassfish). 

Chesar 3 server package has been tested using the following: 

Software 
Operating System  Microsoft Windows 

Product 

Version  Comments 
7, 8, 10  We are not aware of any limitations 

Java 

Database server 

Linux 
JRE 

Network Derby 
Server (free) 
Oracle (commercial) 

Application server  Tomcat 

Browser 

Glassfish 
Internet Explorer 

Mozilla Firefox 

Chrome 

that would prevent Chesar 3 from 
working on Windows Server 2008 or 
2012. 

8 

10.12 

http://www.oracle.com/technetwork/ja
va/javase/downloads/index.html 
http://db.apache.org/derby 

11g, 12c  http://docs.oracle.com/en/database/ 
http://tomcat.apache.org/ 
8 
https://glassfish.java.net/ 
4 
https://www.microsoft.com/en-
11 
gb/download/internet-explorer.aspx 
https://www.mozilla.org/en-
GB/firefox/new/ 
https://www.google.com/chrome/brow
ser/desktop/index.html 

 Unlike Chesar 2, please note that Chesar 3 is not compatible with Postgres db. 

2.3. Security 

The  Chesar  application  contains  a  basic  username  /  password  feature  aimed  at  reducing  the 
risk  of  accidental  modification  of  data.  This  functionality  is  not  intended  to  protect  against 
wilful or malicious attempts to gain access to or modify data. Chesar must be installed within a 
securely protected environment. 

3. Install Chesar 3 server version 

Chesar 3 server version supports different types of databases (Derby and Oracle) and different 
types of application servers.  

This  installation  manual  explains  in  detail  how  to  install  Chesar  3  server  version  with  Derby 
Network  Server  and  with  Tomcat.  It  also  provides  the  Chesar  specific  instructions  for 
installation with Oracle and Glassfish. 

3.1. Set up database server 

Chesar  3  server  version  supports  two  types  of  databases:  free  Derby  Network  Server  and 
commercial Oracle.  

Please read the chapter below that is relevant to your choice. 

3.1.1. Set up Derby Network Server (Java DB Server) 

Install Derby Network Server 

13/06/2016 13:32 

5 (20) 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
See Annex: Install Derby Network Server for the details on how to install Derby Network 
Server. 

Note: Please install latest version of Derby Network Server. 

Start Derby Network Server 
Open command prompt, cd to %DERBY_HOME%\bin and run the following command there: 
startNetworkServer.bat 

You can also change the Derby Network Server port by using the following command: 

startNetworkServer.bat –h <hostname> –p <portnumber> 

For example this command starts Derby server on the port 3306 and allows only local 
connections. 

startNetworkServer.bat –h localhost –p 3306 

The command below would allow connections from any computer: 

startNetworkServer.bat –h 0.0.0.0 –p 3306 

However be aware that allowing connection from any computer may not be the best option 
from the security perspective. 

Create Chesar 3 database 

Start ij tool and createij the database and user for Chesar 3: 

ij 

connect 
'jdbc:derby://<database_server_url>:<port>/<database>;create=true;user=<username

13/06/2016 13:32 

6 (20) 

 
 
 
 
 
 
 
 
 
 
>;password=<password>'; 

For example this command creates the database chesar3, the user chesar3 with the password 
chesar3 

connect 
'jdbc:derby://localhost:3306/chesar3;create=true;user=chesar3;password=chesar3'; 

3.1.2. Set up Oracle Database 

Install Oracle Database 

See http://docs.oracle.com/en/database/ for the details on how to install Oracle database. 

Note: Chesar 3 was tested with Oracle 11g and 12c. 

Create Chesar 3 tablespace and user 

Execute the following commands in SQL Plus: 

create tablespace chesar3  
 datafile '/u02/oradata/orcl/chesar3.dbf'  
 size 100M  
 autoextend on  
 next 50M  
 maxsize 200M;  
grant create session to chesar3 identified by "chesar3";  
grant create table to chesar3;  
grant create view to chesar3;  
grant create sequence to chesar3;  
alter user chesar3 quota unlimited on chesar3;  
alter user chesar3 default tablespace chesar3; 

3.2. Migrate from Chesar 2.3 database to Chesar 3 database 

Note: This is an optional step in case you want to transfer the information available in Chesar 
2.3 database to Chesar 3 database.  

See section 4: Migrate Chesar 2.3 to Chesar 3 for the steps to install and run the migration 
tool. 

3.3. Set up application server (or servlet container) 

Although we have tested Chesar 3 server version with two types of application server: 
lightweight Tomcat and feature-reach Glassfish, we are not aware of any limitations that would 
prevent Chesar 3 from being deployed and run on any other Java EE compatible application 
server.  

 Chesar 3 is compatible with IUCLID 6. It is possible to install both on the same computer 

(physical server or virtual machine), however we recommend to install Chesar 3 under a 
separate Glassfish/Tomcat from the one used for IUCLID 6.   

13/06/2016 13:32 

7 (20) 

 
 
 
 
 
 
 
 
 
 
 
 
Please read the chapter below that is relevant to your choice. 

3.3.1. Set up Tomcat  

See Annex: Install Tomcat for the details on how to install Tomcat. 

3.3.2. Set up Glassfish 

See https://glassfish.java.net/ for the details on how to install Glassfish. 

3.4. Deploy Chesar 3 

Download Chesar 3 server package 

Download the Chesar 3 server package (Chesar-Server-3.0.0.war) from the Chesar website 
(https://chesar.echa.europa.eu/) to your computer. 

Configure Chesar3 

Note: The default Chesar 3 configuration means: 

-  Database vendor is Derby 
-  Derby Network Server is running on the port 3306 
-  Database name is chesar3 
-  Username and password are both chesar3 
- 

Logs folder location is relative to the current working directory:  
<working-dir>\chesar3-logs 

If you have set up the database according to this configuration then you do not need to change 
the database configuration. 

Rename Chesar3 war file to zip. 

Open the zip with a tool like File Explorer or 7Zip, enter the config folder and extract 
application.properties. 

Edit the extracted file application.properties and enter configuration: 

1.  Database connection properties according to the database server (see Set up database 

server): vendor, URL, username and password 

2.  Log configuration properties: log folder location, logging level 

The screenshot below shows the default configuration: 

13/06/2016 13:32 

8 (20) 

 
 
 
 
 
 
 
 
 
 
 
 
Note: Please change the log folder location, otherwise the logs will be written under the 
current working directory. E.g. in case of Tomcat: <Tomcat-install-folder>\bin\chesar3-logs 

Replace the file application.properties from the zip with the edited one. 

Rename the zip file back to war. 

Deploy Chesar 3 war file to Tomcat 

Please read the section below that is relevant to your application server. 

Deploy to Tomcat 

Copy the war file into <Tomcat-install-folder>\webapps 

Soon Chesar should appear among the Applications. It should be running. 

If everything went well, you should be able to login to Chesar by clicking on the name of 
applications in the Path column on the screenshot above. You can also access it via the 
following link: 

http://localhost:8080/Chesar-Server-3.0.0 

In case of problems check the log files in the folder: 

<Tomcat-install-folder>\logs 

13/06/2016 13:32 

9 (20) 

 
 
 
 
 
 
 
 
 
 
 
 
Deploy to Glassfish 

Use the asadmin deploy command: 

<Glassfish-install-folder>/bin/asadmin deploy --contextroot Chesar-Server-3.0.0 
Chesar-Server-3.0.0.war 

In case of problems check the log files in the folder: 

<Glassfish-install-folder>\glassfish\domains\domain1\logs 

4. Migrate Chesar 2.3 to Chesar 3 

This step is needed in case you want to transfer the information available in Chesar 2.3 to 
Chesar 3.  

4.1. Download and install the Chesar 2.3 to Chesar 3 migration tool  

Once you downloaded the migration tool (chesar-migration-tool-1.0.0.zip) from Chesar website 
(https://chesar.echa.europa.eu/) to your computer, you need to unzip it. 

4.2. Checks to do before running the migration tool 

1.  Make sure that Chesar 2.3 application is stopped. 
2.  Do not start Chesar 3 before running the migration tool. If you have already started 
Chesar 3, you should first drop the database and create a new one (see Set up 
database server). 

4.3. Run the migration tool 

1.  Go to the migration tool installation folder, i.e. where you have unzipped the 

migration tool e.g.: C:\\chesar-migration-tool-1.0.0 

2.  Double-click chesar3migration.bat  

3.  The dialog below should appear (the start-up time can take a couple of seconds max ~1 

minute) 

13/06/2016 13:32 

10 (20) 

 
 
 
 
 
 
 
 
 
  
 
 
4.  Configure Source database: 

a.  If Chesar 2.3 was using PostgreSQL database then select 

-  Distributed (Postgresql) in the picklist 
-  URL (e.g.: jdbc:postgresql://localhost:5432/chesar2) 
-  Username (e.g.: postgres) 
-  Password (e.g.: postgres) 

b.  If Chesar 2.3 was using Oracle database then select  

-  Distributed (Oracle) in the picklist 
-  URL (e.g.: jdbc:oracle:thin:@myhost:1521/orcl) 
-  Username (e.g.: chesar2) 
-  Password (e.g.: chesar2) 

Note: take a look at the database.properties file found at: chesar2.3.war/WEB-
INF/classes/database.properties 

5.  Configure Target database:  

a.  If Chesar 3 is using Derby Network Server database then select  

-  Distributed (Derby) in the picklist  
-  URL (e.g.: jdbc:derby://localhost:3306/chesar3) 
-  Username (e.g.: chesar3) 
-  Password (e.g.: chesar3) 

b.  If Chesar 3 is using Oracle database then select  
-  Distributed (Oracle) in the picklist 
-  URL (e.g.: jdbc:oracle:thin:@myhost:1521/orcl) 
-  Username (e.g.: chesar3) 
-  Password (e.g.: chesar3) 

Note: the settings should correspond to the database server set up for Chesar 3 (see 
Set up database server). 

6.  Press Perform migration button to start the migration process.  

13/06/2016 13:32 

11 (20) 

 
 
 
 
  
 
 
 
7.  You can follow the migration step-by-step on the user interface of the migration tool. 
The time needed for completing the migration is correlated to the size of your Chesar 
2.3 database (number of substances), to the number of contributing activities for each 
use and to the number of SCEDs/SpERCs/determinants defined. The migration may last 
from few minutes to few hours.  

8.  When the migration is finalised, a migration report pops up. In this report, you will find a 
summary of what has been migrated with and without errors and if the migration was 
failing in some part. 

13/06/2016 13:32 

12 (20) 

 
 
 
  
  
 
  
 
 
Note: it is normal if 48 determinant types are not migrated (Ignored). They correspond to the 
built-in determinant types available by default in Chesar 2.3. Chesar 3 defines a new set of 
built-in condition of use templates. 

If there were any “failed” or “successful with errors” items, please collect the logs and report 
an issue with ECHA (see section 7: Reporting issues). 

5. Access Chesar 3  

Go to your browser and enter in its URL bar the following:  
http://<host>:<port>/  
E.g.: 
http://myhost:8080/Chesar-Server-3.0.0 

Login:  If  you  have  migrated  your  data  from  Chesar  2.3  to  Chesar  3,  then  the  username  / 
password  for  Chesar  3  will  be  the  same  as  the  one  that  you  used  for  Chesar  2.3.    If  on  the 
other hand you have not migrated data from Chesar 2.3 to Chesar 3, then please log in using 
the using the default username/password: admin/admin. After logging in with admin/admin 
you may at any point create additional users via Box 7. 

6. Regular Backups 

The  Chesar  data  is  precious!  In  the  same  way  as  any  other  application,  it  is  prudent  to  take 
periodic backups of the data. Please store your backups in a safe location - without this backup 
you are at risk of losing data. 

13/06/2016 13:32 

13 (20) 

 
 
 
  
 
 
 
 
 
 
 
 
 
7. Reporting issues 

In  case  you  encounter  problems  or  wish  to  give  other  feedback,  please  use  the  ECHA  online 
contact form: https://echa.europa.eu/contact/helpdesk-contact-form. 

If  the  issue  you  are  reporting  concerns  a  problem  with  installing  or  running  of  Chesar, 
please collect and send us: 

• 

• 

the Chesar log files which can be found at the location configured in 
application.properties file (see Deploy Chesar 3). E.g.: c:/logs/chesar3-logs 
the Application server log files 

o  Tomcat log files: can be found at …\<Tomcat-install-folder>\logs 
o  Glassfish log files: can be found at …\<Glassfish-install-

folder>\glassfish\domains\domain1\logs 

If  the  issue  you  are  reporting  concerns  a  problem  with  migrating  data,  please  collect  and 
send  us  the  Migration  log  files  which  can  be  found  at  …\chesar-migration-tool-1.0.0\chesar3-
logs 

8. Annexes 

8.1. Annex: Install Derby Network Server 

Download Derby Network Server: 

http://db.apache.org/derby/derby_downloads.html 

Version 10 should be used, i.e. 10.12.1.1: 

The installation package contains a folder. Extract this folder to an appropriate location (i.e. 
c:\). 

Edit the setNetworkServerCP.bat 

13/06/2016 13:32 

14 (20) 

 
 
 
 
 
 
 
In the setNetworkServerCP.bat set the “DERBY_INSTALL” variable 

Open command prompt, cd to %DERBY_HOME%\bin and run the following command there: 

setNetworkServerCP.bat 

8.2. Annex: Install Tomcat 

Download Tomcat 8: 

http://tomcat.apache.org/ 

The Windows installer is available: 

13/06/2016 13:32 

15 (20) 

 
 
 
 
 
 
 
 
Double click the installer to start installation. 

13/06/2016 13:32 

16 (20) 

 
 
 
 
 
 
 
 
Warning: if some other application is using the port 8080 (i.e. IUCLID 6) then the port will 
have to be changed. 

13/06/2016 13:32 

17 (20) 

 
 
 
 
 
 
This should start Tomcat. 

13/06/2016 13:32 

18 (20) 

 
 
 
 
 
 
 
Set the maximum memory pool used by Tomcat: 

Check whether Tomcat is running: 

http://localhost:8080 

13/06/2016 13:32 

19 (20) 

 
 
 
 
 
 
CHEMICALS 

EUROPEAN 
AGENCY 
ANNANKATU  18,  P.O.  BOX  400, 
FI-00121 
FINLAND 
HELSINKI, 
ECHA.EUROPA.EU 

13/06/2016 13:32 

20 (20)