forked from OxalisCommunity/oxalis
-
Notifications
You must be signed in to change notification settings - Fork 0
/
install.html
152 lines (147 loc) · 7.51 KB
/
install.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Oxalis installation guide</title>
</head>
<body>
<h1>Installing Oxalis, the Norwegian PEPPOL access point reference implementation.</h1>
<ol>
<li>Download and install Java JDK version 6 or higher (Note: you must install the JDK, the JRE is not sufficient).
</li>
<li>Download and install Apache Tomcat, we recommend version 7.0.22 or higher.</li>
<li>Enable SSL (https) in Tomcat by installing your SSL certificate. This guide assumes that you enable SSL on port
8443.
</li>
<li>Download and install Apache Ant.</li>
<li>If you are running on a Windows machine, Set the following user variables (My Computer -> Properties -> Advanced
-> Environment Variables)
<pre>
JAVA_HOME - should point to the Java JDK installation (ex. C:\Program Files\Java\jdk1.6.0_30
CATALINA_HOME - should point to the Apache Tomcat installation (ex. C:\Program Files\Apache Software Foundation\Tomcat 7.0)
TOMCAT_HOME - should be identical to CATALINA_HOME
ANT_HOME - should point to the Apache Ant installation (ex. C:\Documents and Settings\Administrator\Desktop\apache-ant-1.8.2)</pre>
</li>
<li>
Add Apache Ant to your path (for Windows):
<pre>set PATH=%PATH%;%ANT_HOME%/bin</pre>
</li>
<li>Download and install the Java Net Metro package. This package extends your JDK with a complete
SOAP Web Services stack:
<pre>sudo ant -Dtomcat.home=$TOMCAT_HOME -f metro-on-tomcat.xml install</pre>
If you're on a Windows machine, run this command:
<pre>ant -Dtomcat.home="%TOMCAT_HOME%" -f metro-on-tomcat.xml install</pre>
<p>You should also consider installing Metro into your JDK:
<pre># Installs Metro into the JDK
sudo ant -f metro-on-tomcat.xml install-api
</pre>
</p>
</li>
<li>Install your keystore. We suggest shoving it into the Tomcat installation. Whatever you do, don't forget
to specify the location in the Oxalis configuration file, as specified below.
<p>This is how we would perform this task on a Linux or Mac OS X machine:</p>
<pre>sudo -u tomcat cp ~/keystore.jks $TOMCAT_HOME/conf/keystore</pre>
</li>
<li>Modify <tt>$TOMCAT/conf/catalina.properties</tt> to ensure that the Oxalis specific stuff is loaded by the
Tomcat commons class loader by modifying the
line starting with <tt>shared.loader=</tt>:
<pre>
shared.loader=${catalina.base}/shared/lib,${catalina.home}/shared/lib/*.jar, \
${catalina.base}/shared/lib/oxalis,${catalina.base}/shared/lib/oxalis/*.jar
</pre>
<p>
This declaration indicates to Tomcat that the supplied directories and .jar-files should be made available to the shared loader, which is the
parent class loader for all web application class loaders.
</p>
<p>From release 1.13 and upward, this declaration is only used to locate the <code>oxalis-web.properties</code>,
henceforth you may omit this step and simply shove the <code>oxalis-web.properties</code>
file into the <code>$TOMCAT_HOME/lib</code> directory, which I prefer.
</p>
</li>
<li>Copy the supplied <tt>sample-oxalis-web.properties</tt> file to either <tt>$TOMCAT_HOME/shared/lib/oxalis/oxalis-web.properties</tt>
or <tt>$TOMCAT_HOME/lib</tt>.
This is how you would do it on a Linux or Mac OS X machine:
<pre>cp sample-oxalis-web.properties $TOMCAT_HOME/shared/lib/oxalis/oxalis-web.properties</pre>
</li>
<li>Edit the Oxalis configuration file:
<pre>sudo -u tomcat vi $TOMCAT_HOME/shared/lib/oxalis-web.properties</pre>
</li>
<li>Start Tomcat</li>
<li>You should now be able to see the WSDL by going to the address:
<a href="https://localhost:8443/oxalis/accessPointService?wsdl">https://localhost:8443/oxalis/accessPointService?wsdl</a>
</li>
</ol>
<h2>Pluggable persistence using a JNDI data source</h2>
<p>If you intend to roll your own persistence mechanism by implementing the <code>MessageRepository</code> interface,
this is how you do it:
<ol>
<li>Configure your JDBC data source by adding this XML fragment to <tt>$TOMCAT_HOME/conf/server.xml</tt> between
the <code><GlobalNamingResources></code> tags in order to
create a global data source:
<pre>
<Resource name="jdbc/sr"
auth="Container"
type="javax.sql.DataSource"
maxActive="100"
maxIdle="30"
maxWait="10000"
username="xxxxxxxxx" <-------- Don't forget to change this
password="*********" <-------- Don't forget to change this
driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/sendregning?autoReconnect=true"
removeAbandoned="true"
removeAbandonedTimeout="60"
logAbandoned="true"
/>
</pre>
</li>
<li>Link the global data source to the JNDI ENC name used by Oxalis, by adding this to <code>$TOMCAT_HOME/conf/context.xml</code>:
<pre>
<ResourceLink name="jdbc/peppol-ap" global="jdbc/sr" type="javax.sql.DataSource"/>
</pre>
</li>
<li>Create an implementation of <code>MessageRepository</code>.
<p>Don't forget to include the file <code>META-INF/services/eu.peppol.start.persistence.MessageRepository</code>
in the root of your .jar file in order to let Oxalis
discover your implementation using the standard Java services location mechanism.
</p>
</li>
<li>Edit the <code>oxalis-web.properties</code>-file, specifying where your custom implementation is located, by
adding
the property <code>oxalis.persistence.class.path</code> property.
<p>Here is an example, in which the implementation is simply loaded from the compiled output directory (yes, I
am using Maven):
<pre>
# From where do we load the persistence module? NOTE! Must end with either / or .jar
oxalis.persistence.class.path = file:///Users/steinar/src/sr-peppol/aksesspunkt/oxalis-persistence/target/classes/
</pre>
</p>
<p>Here is another example, in which the assembled .jar-file is being used:
<pre>
# From where do we load the persistence module? NOTE! Must end with either / or .jar
oxalis.persistence.class.path = file:///Users/steinar/src/sr-peppol/aksesspunkt/oxalis-persistence/target/oxalis-persistence-1.0.7.jar
</pre>
</p>
<p>Todo: in a future release of Oxalis, the class path should be specified as a comma separated list of URLs, allowing the
declaration of several directories and .jar-files. </p>
</li>
</ol>
<p>The illustration below depicts how the various class loaders work togheter in order to load the pluggable
persistence components is loaded using a custom class loader.
<div>
<img src="custom-class-loading.png" alt="Illustration of custom class loading"
width="480" height="600" />
</div>
This is how it works:
<ol>
<li>Oxalis will scan the class path for the file <code>oxalis-web.properties</code>, which it finds in
<code>/shared/lib/oxalis</code> or perhaps in the <code>$TOMCAT_HOME/lib</code> if you placed the file there.
</li>
<li>Once found, the file is opened and the property <code>oxalis.peristence.class.path</code> is consulted.</li>
<li>A custom class loader is created, which will load the pluggable components from the location found in
the item above.
</li>
</ol>
</p>
</body>
</html>