1 mukherjeea 1.7 This is a draft version of the MIR (myGrid Information Reposito-
2 ry) INSTALLATION DOCUMENT. It provides details of the basic steps
3 required to install an MIR. It is assumed that you have read the
|
4 egglestones 1.6 myGrid installation guide before working through this document.
5
|
6 mukherjeea 1.7 Storage and retrieval of data stored in an MIR is provided
7 through the MIR web-service interface. This must be deployed in a
8 web-server. Operations on the web-service interface access an
9 external database. This access is provided through Hibernate,
10 which is a database connection layer built on top of JDBC.
11
12 LSIDs are used as keys in the MIR database schema. LSIDs are
13 globally unique identifiers for data objects, and are generated
14 by an LSID authority. myGrid provide an implementation of an
15 lsid-authority, which can be found in directory gridd-authority.
16
17 The process of installing the MIR consists of setting up a
18 database, modifying various configuration files to allow the MIR
19 to access the database, building the MIR web-service and deploy-
20 ing it in a web-server. Individual steps in this installation
21 process are described below. The mygrid project has chosen Tomcat
22 as the platform for delivering web-services. The following docu-
23 ment assumes that the web-service will be installed into Tomcat,
24 with mySQL being used as the back-end database. This process has
25 been tested on Tomcat version 5.0.28, and on mySQL version
26 4.0.20.a, although it is expected to work on other versions of
27 mukherjeea 1.7 Tomcat and mySQL.
|
28 egglestones 1.6
|
29 mukherjeea 1.7 The directory in which MIR software can be found is referred to
|
30 egglestones 1.6 as <mir-home> in this docuemnt
|
31 mukherjeea 1.1
32 1. Checkout the mygrid/MIR module from the CVS
33
|
34 mukherjeea 1.7 2. Modify the configuration files to reflect the correct details
35 about the database.
|
36 mukherjeea 1.1
|
37 egglestones 1.6 a. Modify <mir-home>/config/hibernate.cfg.xml:
|
38 mukherjeea 1.1
|
39 sharmann 1.8 <property name="connection.url">jdbc:mysql://localhost:3306/mygrid_mir</property>
|
40 mukherjeea 1.7 <property name="dialect">net.sf.hibernate.dialect.MySQLDialect</property>
41 <property name="connection.username">MYSQL USER-NAME</property>
42 <property name="connection.password">MYSQL PASSWORD</property>
43 <property name="connection.driver_class">org.gjt.mm.mysql.Driver</property>
44
45 b. Modify <mir-home>/config/hibernate.properties
46
47 hibernate.dialect net.sf.hibernate.dialect.MySQLDialect
48 hibernate.connection.driver_class org.gjt.mm.mysql.Driver
|
49 sharmann 1.8 hibernate.connection.url jdbc:mysql://localhost:3306/mygrid_mir
|
50 mukherjeea 1.7 hibernate.connection.username <MYSQL USERNAME>
51 hibernate.connection.password <MYSQL PASSWORD>
52 hibernate.jdbc.batch_size=0
53
|
54 egglestones 1.6 c. Modify <mir-home>/config/authority.properties.
|
55 mukherjeea 1.7
56 This specifies details of how to access an LSID authority
57 to generate new LSIDs. mygrid.mir.proxyhost and mygrid.mir.proxyport
58 are only necessary if your web-connection is through an http-proxy.
59 If you are connected to the web directly, these properties should be
60 commented out by inserting the # symbol at the start of each line.
|
61 egglestones 1.6
62 mygrid.mir.jdbc.driver=org.gjt.mm.mysql.Driver
63 mygrid.lsid.providerauthority=www.mygrid.org.uk
64 mygrid.mir.jdbc.url=jdbc:mysql://localhost:3306/<DB_NAME>
65 mygrid.mir.jdbc.user=<MYSQL USERNAME>
66 mygrid.mir.jdbc.password=<MYSQL PASSWORD>
67 mygrid.mir.jdbc.pool.max=20
68 mygrid.lsid.assigning.service=<ADDRESS OF ASSIGNING SERVICE FOR LSIDS>
69
70 mygrid.mir.proxyhost=<PROXY ADDRESS>
71 mygrid.mir.proxyport=<PROXY PORT>
72
|
73 mukherjeea 1.7 3. Edit <mir-home>/mir.properties to reflect the port on which the
74 service should be running, and to provide details of the database
75 connection. Properties database.schema and database.catalog should
76 be left empty.
|
77 mukherjeea 1.1
|
78 egglestones 1.6 4. CD to directory <mygrid-home>. Run "antmerge".
|
79 mukherjeea 1.1
|
80 mukherjeea 1.7 5. Run "ant init-db" in the root directory. This will create all the
81 tables in the database. Please make sure that the database is already
82 created, and has correct access permissions for the USER.
|
83 mukherjeea 1.1
|
84 sharmann 1.8 # mysql --user=root
85 mysql> create database mygrid_mir;
86 mysql> connect mygrid_mir;
87 mysql> \. mir-schema.sql
88 mysql> quit
89
90 Make sure the chosen MySQL user has adequate permissions for updating this
91 database.
92
93 6. Start Tomcat and run "ant tomcat.install" - this will deploy the MIR web
94 service.
|
95 mukherjeea 1.1
|
96 mukherjeea 1.3 OR
|
97 mukherjeea 1.1
|
98 sharmann 1.8 Use the Tomcat Manager web page to deploy the file webapps/mir-0.2.war.
|
99 mukherjeea 1.1
|
100 mukherjeea 1.7 7. Restart tomcat. Verify the deployment of MIR by going to
|
101 sharmann 1.8
|
102 mukherjeea 1.3 http://<host>:<port>/mir-<version>/services/MIRAccessService?wsdl
103
|
104 mukherjeea 1.7 8. Use the test client (PopulateMIRTest.java) to create test data by
105 running "ant dummy". See the section below for details.
|
106 mukherjeea 1.5
|
107 mukherjeea 1.7 INITIALIZING MIR (POPULATING WITH INITIAL DATA)
108 -----------------------------------------------
109
110 There are two ways to populate MIR with some initial data. Some
111 contextual data for example, Person, Organization, Study, Pro-
112 gramme, ExperimentDesign etc) are required to enact workflows for
113 a Person entity, and store the results in the MIR corresponding
114 to correct Study and ExperimentDesign.
115
116 The first method is to use the "ant dummy" target which will pop-
117 ulate MIR with some test data. But, these are coded in uk.org.my-
118 grid.mir.test.PopulateMIRTest and, in case you want to change the
119 data, you need to change the code and execute it.
120
121 If you do not have the source code, or you want to avoid changing
122 the code, please use the other method of initializing MIR de-
123 scribed in the User Guide.
|
124 mukherjeea 1.1
125 IMPORTANT POINTS
126 ----------------
127
|
128 mukherjeea 1.7 1. The hibernate mapping files are stored in the hibernate folder
129 and are copied into the source tree during the build process.
130 These mappings reflect the data model and the associations
131 between the entities. Any change in these files would require a
132 complete database reinitialization, and perhaps code
133 modifications.
134
135 2. The java files in src/uk/org/mygrid/mir/domain are responsible
136 for the creation/updation of the entities. The general rule for
137 persisting a collection is:
138
139 Each parent object may have a child or a list of children.
140 These may be provided by reference or by value. If only the LSIDs
141 of the children are provided inside the parent object to be
142 stored, this will imply that the children (whose LSIDs are
143 passed within the parent) are already created. Hence, the entity
144 manager will attempt to retrieve the children based on the LSIDs
145 (which are the primary key), and use them as references within
146 the parent object. But, if the children are passed by value, this
147 implies that the children are to be created before storing the
148 parent. In such cases, the entity manager will first check whether
149 mukherjeea 1.7 the children have LSIDs preassigned or not. If the children have
150 preassigned LSIDs, the entity manager searches the current session
151 and then the store for already persistent entities with those LSIDs.
152 If such instances are found, then they are used as references,
153 otherwise a new instance is created with the pre-assigned LSID.
154 If the children do not have any pre-assigned LSID, this will always
155 mean that they are to be created for the first time.
156
157 Hibernate recommends that the children are created and saved before
158 the parents. The only exception to this rule is in the case of
159 one-to-one mapping, where the parent ID is needed in the child
160 table. In such case, the parent is created and saved first without
161 the child being referred inside it. After that the child is created
162 and associated with the parent.
|
163 mukherjeea 1.1
|
164 mukherjeea 1.7 NOTE
|
165 mukherjeea 1.1 ----
166
|
167 mukherjeea 1.7 Sometimes, during deployment (axis deployment), tomcat complains
168 about a missing class, though the class is inside the jar files
169 being copied onto tomcat. In such cases, if tomcat is restarted
170 and the deployment target is executed again, the service is suc-
171 cessfully deployed. The occurrence of this problem is erratic in
172 nature, and sometimes may require a couple of more attempts to
173 deploy - but ultimately the service gets deployed.
174
|
Return to
INSTALLATION.TXT
CVS log
Up to [Development] / mygrid / MIR