Refactor documentation for JDK 12/Tomcat 9.

archiver-appliance · Nov 13, 2019 · 57fbbb2 · 57fbbb2
1 parent 68b1d67
commit 57fbbb2
Show file tree

Hide file tree

Showing 26 changed files with 196 additions and 93 deletions.
diff --git a/docs/customization.html b/docs/customization.html
@@ -61,6 +61,10 @@
 <section id="Site_Specific_Builds">
 <h3>Site specific builds</h3>
 The archiver appliance offers you the ability to customize the WAR files generated by the build in these ways.
+<div class="noteafterlist"> Han maintains a set of scripts for <a href="https://github.com/jeonghanlee/epicsarchiverap-sites">site specific installs</a>.
+This is an excellent starting off point for folks who wish to build their own deployment bundles.
+This is tested against CentOS; but should be easily extensible for other distributions.
+</div>
 <ol>
 <li>The <code>src/sitespecific</code> folder contains materials specific to your site.
 You can use the environment variable <code>ARCHAPPL_SITEID</code> to control which set of sitespecific files are included in the generated WARS.
@@ -78,10 +82,14 @@ <h3>Site specific builds</h3>
 <li>If you do not set the <code>ARCHAPPL_APPLIANCES</code> environment variable, the <code>appliances.xml</code> is discovered in a similar fashion.</li>
 <li>There is also a site specific properties file called <code>archappl.properties</code> that is discovered in a similar fashion. The properties in this file are used to control some of the other customizations of the archiver appliance.</li>
 </ol>
-<figure>
-<img class="img-responsive" src="images/archappl_siteid.png"/>
-<figcaption>Using the ARCHAPPL_SITEID to customize the contents of the generated WAR files.</figcaption>
-</figure>
+<pre class="bash_output"><code>[ epicsarchiverap ]$ ls -ltr src/sitespecific/
+total 0
+drwxr-xr-x 3 mshankar cd 28 Jun 21 10:40 tests
+drwxr-xr-x 3 mshankar cd 45 Sep  9 16:03 slacdev
+[ epicsarchiverap ]$ export ARCHAPPL_SITEID=slacdev
+[ epicsarchiverap ]$ ant 
+Buildfile: /workspace/epicsarchiverap/build.xml
+     [echo] Building the archiver appliance for the site slacdev</code></pre>
 </li>
 <li>
 The archiver appliance uses <a href="http://ant.apache.org/">Apache Ant</a> for its builds. 

diff --git a/docs/details.html b/docs/details.html
@@ -83,10 +83,10 @@ <h3>System requirements</h3>
 These are the prerequisites for the EPICS archiver appliance.
 <ul>
 <li>A recent version of Linux, definitely 64 bit Linux for production systems. If using RedHat, we should aim for RedHat 6.1.</li>
-<li>JDK 1.12 - definitely the 64 bit version for production systems. We need the JDK, <b>not</b> the JRE.</li>
+<li>JDK 1.12+ - definitely the 64 bit version for production systems. We need the JDK, <b>not</b> the JRE.</li>
 <li>A recent version of Tomcat 9.x; preferably <code>apache-tomcat-9.0.20</code> or later.</li>
 <li>The management UI works best with a recent version of Firefox or Chrome.</li>
-<li>By default, the EPICS archiver appliance uses a bundled version of <a href="https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.epics%22%20AND%20a%3A%22caj%22">CAJ</a>.</li>
+<li>By default, the EPICS archiver appliance uses a bundled versions of the Java CA and PVA libraries from <a href="https://github.com/epics-base/epicsCoreJava">EPICS base</a>.</li>
 </ul>
 
 Optionally, we'd need
@@ -201,13 +201,16 @@ <h3>Clustering</h3>
 
 <section id="scripting">
 <h3>Scripting</h3>
-The archiver appliance comes with a web interface that has support for various business processes. 
-The web interface communicates with the server principally using JSON/HTTP. 
-The same web service calls are also available for use from external scripting tools like Python. 
-<figure>
-<img class="img-responsive" src="images/pythonscript.png"/>
-<figcaption>A sample python script that prints out all the PVs in the cluster of appliances.</figcaption>
-</figure> 
+The archiver appliance comes with a web UI that has support for various business processes like adding PV's to the archivers etc. 
+The web UI communicates with the server principally using JSON/HTTP web service calls. 
+The same web service calls are also available for use from external scripting tools like Python.
+<pre class="bash_output"><code>#!/usr/bin/env python
+
+import requests
+
+resp = requests.get("http://archappl.slac.stanford.edu/mgmt/bpl/getAllPVs?pv=VPIO:IN20:111:VRA*")
+print("\n".join(resp.json()))</code></pre>
+
 Click <a href="api/mgmt_scriptables.html" target="_blank">here</a> for a list of business logic accesible thru scripting.
 </section>
 

diff --git a/docs/developersguide.html b/docs/developersguide.html
@@ -44,10 +44,28 @@
 <h3>Prerequisites</h3>
 Please see the <a href="details.html#SystemRequirements">details</a> page for prerequisites to build and test the EPICS Archiver Appliance.
 An installation of Tomcat is required to build successfully; this is located using the environment variable <code>TOMCAT_HOME</code>.
-Use something like
-<figure>
-<img class="img-responsive" src="images/tomcathome.png"/>
-</figure> 
+Use something like <pre class="bash_output"><code>[ epicsarchiverap ]$ echo $TOMCAT_HOME
+/opt/local/tomcat/latest
+[ epicsarchiverap ]$ ls -l $TOMCAT_HOME/
+drwxr-x---   3 mshankar cd  4096 Oct 29 18:25 bin
+-rw-r-----   1 mshankar cd 19182 May  3  2019 BUILDING.txt
+drwx------   3 mshankar cd   254 Jul 29 14:41 conf
+drwx------   2 mshankar cd   238 May 22 15:43 conf_from_install
+drwxr-xr-x+  2 mshankar cd   238 May 22 15:44 conf_original
+-rw-r-----   1 mshankar cd  5407 May  3  2019 CONTRIBUTING.md
+drwxr-x---   2 mshankar cd  4096 Sep 17 18:13 lib
+-rw-r-----   1 mshankar cd 57092 May  3  2019 LICENSE
+drwxr-x---   2 mshankar cd   193 Nov 11 16:58 logs
+-rw-r-----   1 mshankar cd  2333 May  3  2019 NOTICE
+-rw-r-----   1 mshankar cd  3255 May  3  2019 README.md
+-rw-r-----   1 mshankar cd  6852 May  3  2019 RELEASE-NOTES
+-rw-r-----   1 mshankar cd 16262 May  3  2019 RUNNING.txt
+drwxr-x---   2 mshankar cd    30 Sep 17 18:19 temp
+drwxr-x---  11 mshankar cd   205 Nov 11 16:58 webapps
+drwxr-x---   3 mshankar cd    22 May 22 15:55 work
+[ epicsarchiverap ]$</code></pre> 
+
+
 By default, Tomcat sets up a HTTP listener on port 8080.
 You can change this in the Tomcat server.xml to avoid collision with other folks running Tomcat.
 For example, here I have changed this to 17665.
@@ -75,18 +93,24 @@ <h3>Building</h3>
 We use <a href="http://ant.apache.org/">Apache Ant</a> for building. 
 If you have a Eclipse workspace called <code>workspace</code> and the EPICS archiver appliance code checked out into a folder called <code>epicsarchiverap</code>, 
 then the build script is run by calling ant from within <code>workspace/epicsarchiverap</code>.
-<figure>
-<img class="img-responsive" src="images/build_ant.png"/>
-<figcaption>Using ant to initiate a build.</figcaption>
-</figure> 
-
+<pre class="bash_output"><code>[ epicsarchiverap ]$ ant
+Buildfile: /workspace/epicsarchiverap/build.xml
+     [echo] Building the archiver appliance for the site tests
+...
+wars:
+      [tar] Building tar: /workspace/archappl_v0.0.1_SNAPSHOT_13-November-2019T14-48-26.tar.gz
+
+BUILD SUCCESSFUL
+Total time: 21 seconds
+[ epicsarchiverap ]$ 
+</code></pre>
 
 The default target builds the install package and the various wars and places them into the parent folder.
-<figure>
-<img class="img-responsive" src="images/built_wars.png"/>
-</figure> 
-</section>
-
+<pre class="bash_output"><code>
+[ epicsarchiverap ]$ ls -ltra ../archappl_*.tar.gz
+-rw-r--r-- 1 mshankar cd 154000860 Nov 13 14:48 ../archappl_v0.0.1_SNAPSHOT_13-November-2019T14-48-26.tar.gz
+[ epicsarchiverap ]$ 
+</code></pre>
 
 <section>
 <h3>Deploying</h3>

diff --git a/docs/docs.css b/docs/docs.css
@@ -25,6 +25,23 @@ img.imageshowingstep {
 	margin-bottom: 0.25em;
 }
 
+pre.bash_output {
+	background: black;
+	color: cyan;
+	font-family: monospace;
+}
+
+span.rm_txt {
+	text-decoration: line-through;
+	font-style: italic;
+	color: red;
+}
+
+span.add_txt {
+	font-weight: bold; 	
+	color: orange;
+}
+
 div.noteafterlist { 
 	margin-top: 0.5em;
 }

diff --git a/docs/images/CAJContext.png b/docs/images/CAJContext.png
diff --git a/docs/images/appliancesxml.png b/docs/images/appliancesxml.png
diff --git a/docs/images/archappl_siteid.png b/docs/images/archappl_siteid.png
diff --git a/docs/images/build_ant.png b/docs/images/build_ant.png
diff --git a/docs/images/buildingjsvc.png b/docs/images/buildingjsvc.png
diff --git a/docs/images/built_wars.png b/docs/images/built_wars.png
diff --git a/docs/images/connpool.png b/docs/images/connpool.png
diff --git a/docs/images/deployMultiple.png b/docs/images/deployMultiple.png
diff --git a/docs/images/expandedtargz.png b/docs/images/expandedtargz.png
diff --git a/docs/images/javaversion.png b/docs/images/javaversion.png
diff --git a/docs/images/pythonscript.png b/docs/images/pythonscript.png
diff --git a/docs/images/readyforUIrequests.png b/docs/images/readyforUIrequests.png
diff --git a/docs/images/runqascript.png b/docs/images/runqascript.png
diff --git a/docs/images/slasharch.png b/docs/images/slasharch.png
diff --git a/docs/images/targzs.png b/docs/images/targzs.png
diff --git a/docs/images/tomcathome.png b/docs/images/tomcathome.png
diff --git a/docs/images/tomcathttpconnector.png b/docs/images/tomcathttpconnector.png
diff --git a/docs/images/tomcatlib1.png b/docs/images/tomcatlib1.png