Tooling

Cygwin

  • Download and Install Cygwin with whatever options you want
  • Required packages:
    • devel/subversion (ant wants svnversion.exe at least)
  • I have found the following useful.
    • devel/libxml2
    • doc/libxslt
    • editors/vim
    • web/wget
    • Cygwin Here

Subversion

  • Donwload and Install the latest Subversion client
  • Edit subversion config file per the instructions on the DevSetup page
    • $HOME/ApplicationData/Subversion/config for TortoiseSVN
    • $HOME/.subversion/config or /cygwin/etc/subversion/config for Cygwin
      • Cygwin doesn't create a default subversion/config for you to play with. Here's the minimum necessary config: 
        [miscellany]
enable-auto-props = yes
[auto-props]
*.java = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.py = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.pl = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.pm = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.html = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.txt = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.sql = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.css = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.jsp = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.js = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.ftl = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xml = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.dtd = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xsd = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xsl = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xslt = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.wsdd = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.wsdl = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.rdf = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.owl = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xmap = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.xconf = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.pom = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.ini = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.nsi = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.nsh = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.properties = svn:eol-style=native;svn:keywords=Id HeadURL Revision
*.exe = svn:executable
*.sh = svn:eol-style=native;svn:executable
*.bat = svn:eol-style=CRLF;svn:executable

Java

  • Download Java JDK 1.5x
  • Install it in a directory w/o spaces (e.g. c:\tools\java)
  • Ensure that JAVA_HOME is set correctly
    • Right Click on My computer, Properties, Advanced Tab, Environment Variables, System Variables
    • Select New to create JAVA_HOME and set it to the directory where you installed the JDK, e.g. c:\tools\java
    • Add the java bin directory (e.g., c:\tools\java\bin) to the path environment variable

Ant

  • Download latest version of Apache Ant
  • unzip it into a directory without spaces (e.g., c:\tools\ant\)
  • Add the bin directory from the installation to your path

Maven

  • Download Maven version 2.0.8
  • Place it in a folder that you can add to your path
  • Right Click on My computer, Properties, Advanced Tab, Environment Variables. System Variables
  • Edit the Path to put the bin folder of maven at the end (e.g., c:\tools\maven-2.0.8\bin)
  • Open up a cygwin command prompt and type mvn
  • A .m2 directory should have been created in c:\Documents and Setting\username
  • Create a settings.xml file in that directory with content similar to the following (depending on where you installed cywgin and where you want the topaz project installs to go). You don't need to use your cygiwn home, but do make sure all paths have no spaces in them. 
    <settings>
  <pluginGroups>
    <pluginGroup>org.topazproject.plugins</pluginGroup>
  </pluginGroups>
  <localRepository>c:/cygwin/home/LOCAL USERNAME/.m2/repository</localRepository>
  <profiles>
    <profile>
      <id>build-env</id>
      <properties>
        <topazproject.install.dir>c:/cygwin/home/LOCAL USERNAME/topazproject-install</topazproject.install.dir>
      </properties>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>build-env</activeProfile>
  </activeProfiles>
  <servers>
    <server>
      <id>topaz</id>
      <username>TRAC USERNAME</username>
      <password>TRAC PASSWORD</password>
    </server>
  </servers>
</settings>
  • The following is a nice setting for eclipse, and to provide enough memory to ingest/imageMagick on a desktop.
    • Right Click on My computer, Properties, Advanced Tab, Environment Variables, System Variables
    • Select New and create variable name MAVEN_OPTS
    • Set Variable value to: 
      -Xmx1024M -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8085,server=y,suspend=n

PostgreSQL

  • Download and install latest version of PostgreSQL
  • You should remember the username and passwords you chose for the installation
  • Recommend to install as a service, but you can later choose manual startup in Windows Services if you don't want it automatically started everytime Windows boots. Reason for recommendation is so that the proper accounts are created.
  • Change the Locale to English, United States and the Encoding to UTF-8
  • Leave the defaults for everything else
  • After installation, launch pgAdmin III and connect to your local database server
  • Create a user called plosone
  • Set the password to something you will remember.
    • Create a new database called plosdb with encoding set to UTF8.
  • Right click on database plosdb and select Properties. Set the owner to the user plosone which you created earlier.

Image Magick

  • Download the latest windows (dll 16) version of Image Magick
  • Install with defaults, but install it into a directory without spaces

Eclipse

See EclipseSetup

Configuration

Checkout source

  • Start up cygwin
  • Make a directory where you want to checkout the source
  • cd into that directory
  • svn co --username USERNAME http://svn.topazproject.org/svn/head
  • Open up the file head/plos/ecqs-bundle/properties/build.properties
    • Edit the line jakarta-tomcat.keystore.dname.cn to be the common name for your machine (can be localhost)
    • Edit the line jakarta-tomcat.keystore.dname.o to just = the empty string

First Build

  • cd to directory where you checked out the source tree
  • cd head
  • mvn
  • Make sure the build is successful - look at DevSetup for additional notes on building if there are failures.

Install Tasks

  • Import the cert into key store from a DOS cmd window 
    On windows:
 to check if you already have one:
"C:\Program Files\Java\jdk1.5\bin\keytool" -list -trustcacerts -alias jakarta-tomcat -storepass changeit -keystore "C:\Program Files\Java\jdk1.5\jre\lib\security\cacerts"

 to delete one if already existing and ecqs has changed since the certificate was created:
"C:\Program Files\Java\jdk1.5\bin\keytool" -delete -trustcacerts -alias jakarta-tomcat -storepass changeit -keystore "C:\Program Files\Java\jdk1.5\jre\lib\security\cacerts"

 to import:
"C:\Program Files\Java\jdk1.5\bin\keytool" -import -trustcacerts -alias jakarta-tomcat -storepass changeit -file D:\java\topaz-install\esup-cas-quick-start-2.0.6-1\tmp\cert.pkcs7 -keystore "C:\Program Files\Java\jdk1.5\jre\lib\security\cacerts"
  • Copy /head/packages/cas/src/main/resources/cas.xml to c:\etc\topaz (Create the directory if it doesn't exist)
    • Replace all FQHN references with localhost
    • Change the db/user, db/password, and db/url properties to the plosone user password you created when installing postgres
  • Copy head/plos/registration/webapp/target/plos-registration.war into the webapps directory of the cas tomcat installation (e.g., ~/topazproject-install/esup-cas-quick-start-2.0.6-1/jakarta-tomcat-5.0.28/webapps)
  • run mvn ant-tasks:ecqs-start from the head directory

  • Copy /head/packages/fedora/src/main/resources/fedora.fcfg to c:\etc\topaz
  • Copy /head/packages/mulgara/src/main/resources/mulgara.xml to c:\etc\topaz
    • Change the two directories to a directory on your machine that won't be deleted
  • Copy /head/packages/ambra/src/main/resources/ambra.xml to c:\etc\topaz
    • Change the utilities/image-magick variables to reflect how the program is installed on your machine
    • Change the search/indexpath to a path located on your machine that won't be deleted
    • Edit app-context to read /ambra-webapp

  • Edit the /head/plos/webapp/pom.xml so that the keystore in the jetty plugin config is pointing to a valid file from the CAS install. You may want to add the following as well. The first two are optional if you imported the cert into your java keystore: 
    <systemProperty>  <!-- if you don't want to import the cert into your systemwide java keystore, you can point to here -->
  <name>javax.net.ssl.trustStore</name>
  <value></value>
</systemProperty>
<systemProperty>
  <name>javax.net.ssl.trustStorePassword</name>
  <value>changeit</value>
</systemProperty>
<systemProperty> <!-- values for location of ingest files -->
  <name>pub.spring.ingest.source</name>
  <value>/tmp/ingest/</value>
</systemProperty>
<systemProperty>
  <name>pub.spring.ingest.destination</name>
  <value>/tmp/ingest/</value>
</systemProperty>
  <systemProperty>  <!-- search webapp URL -->
  <name>topaz.fedoragsearch.urls.url</name>
  <value>http://localhost:9092/ws-search-webapp/services/FedoraGenericSearchServicePort</value>
</systemProperty>
    • OR as a preferred alternative, since maven pom files are under source control (and we don't want to inadvertantly commit a dev machine specific version), declare the environment variables as invocation arguments to a maven target (usually jetty:run for starting up ambra): 
      -Djavax.net.ssl.trustStore=/etc/topaz/keystore.jks -Djavax.net.ssl.trustStorePassword=changeit -Dtopaz.fedoragsearch.urls.url=http://localhost:9092/ws-search-webapp/services/FedoraGenericSearchServicePort jetty:run

  • You can copy article zip files to the ingest.source directory set above if you have some
  • Follow the directions here: DevSetup#Installingandrunningstuffonyourlocalmachineinthespecifiedorder to start up all the services
    • If you encounter a timeout error starting up fedora, you can add a number in seconds for how long the script should wait before declaring an error. Try adding 120 (or a larger number) at the end of this line 
      "%JAVA_HOME%\bin\java" -cp %TC%\webapps\fedora\WEB-INF\classes;"%SERVER_LIBS%" -Djavax.net.ssl.trustStore="%FEDORA_HOME%\server\truststore" -Djavax.net.ssl.trustStorePassword=tomcat -Dfedora.home=%FEDORA_HOME% -Dtomcat.dir=%TOMCAT_DIR% fedora.server.utilities.status.ServerStatusTool watch-startup
  • If there are multiple developers working on the same network, you should edit the ambra caching configuration so that your caches do not talk to one another.
    • Edit plos/webapp/src/main/webapp/src/main/resources/ehcache.xml and comment out the following in each cache: 
        <cache ...>
    <!--
      <bootstrapCacheLoaderFactory
        class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"/>
      <cacheEventListenerFactory
        class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"/>
     -->
  <.../cache>
    • OR edit the multicast group address/port in ehcache.xml (and maybe also the listner on port 8111?)
    • OR you can disable caching entirely by setting the following system property in plos/webapp/pom.xml 
        net.sf.ehcache.disabled=true
  • If you want to be able to send mail to test functionality, point cas.xml and ambra.xml mailhost elements at a working mail server.
  • If you want to have logging turned on, put a log4j.xml config file in etc/topaz. A sample one here : 
    <?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="console" class="org.apache.log4j.ConsoleAppender">
    <param name="Target" value="System.out"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%-5p [%t] %c{1} - %m%n"/>
    </layout>
  </appender>

  <appender name="rolling" class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="_ambra.log"/>
    <param name="MaxFileSize" value="10MB"/>
    <param name="Encoding" value="UTF-8"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="&lt;%d&gt; &lt;%p&gt; &lt;%F:%M&gt;-%m%n"/>
    </layout>
  </appender>

  <logger name="com.opensymphony.xwork.interceptor.TimerInterceptor">
    <level value="debug"/>
  </logger>

  <logger name="org.plos">
    <level value="debug"/>
  </logger>

   <logger name="edu.yale">
    <level value="debug"/>
  </logger>

  <logger name="org.topazproject">
    <level value="debug"/>
  </logger>

  <root>
    <priority value ="info" />
    <appender-ref ref="console" />
    <appender-ref ref="rolling" />
  </root>

</log4j:configuration>

Data Bootstrapping

A certain amount of core data is required to exist in the app's' data store to be able to successfully bring up and navigate the web application in a browser.

An Admin User

A user with "admin" role must exist in the data store to perform admin tasks such as article ingesting.

To stub an admin user having the credentials plosadmin@gmail.com/foobar: 

your-src-root/plos/libs/runscripts/mvn -Prunitql exec:java -Dargs="-ef /an/arbitrary/dir/adminUser.itql" -f pom.xml

where adminUser.itql is a saved file containing: 

%id = "1"
%name = "admin"
%email = "plosadmin@gmail.com"
%psqlid = "'CI8V9NFWLSBK1B9UBZ3S1NJW5NKF54DQ'"

.alias set foaf http://xmlns.com/foaf/0.1/
.alias set address http://wymiwyg.org/ontologies/foaf/postaddress#

# Models
%users = "<rmi://localhost/topazproject#filter:model=users>"
%prof = "<rmi://localhost/topazproject#filter:model=profiles>"
%grants = "<rmi://localhost/topazproject#filter:model=grants>"

# Ids
%authid = "<info:doi/10.1371/authids/$id>"
%userid = "<info:doi/10.1371/account/$id>"
%profid = "<info:doi/10.1371/profile/$id>"
%admin  = "<info:doi/10.1371/roles/$id>"

%permall = "<topaz:permissions#all>"

insert
  ${authid} <topaz:realm>            'local'
  ${authid} <rdf:value>              ${psqlid}
  ${userid} <rdf:type>               <foaf:OnlineAccount>
  ${userid} <topaz:hasAuthId>        ${authid}
  ${userid} <topaz:accountState>     '0'^^<xsd:int>
  into ${users};

insert
  ${profid} <rdf:type>               <foaf:Person>         
  ${profid} <address:town>           'San Francisco'
  ${profid} <address:country>        'Uganda'
  ${profid} <foaf:mbox>              <mailto:${email}>
  ${profid} <foaf:givenname>         'plos'
  ${profid} <foaf:surname>           '${name}'
  ${profid} <topaz:displayName>      'plos${name}'
  ${profid} <foaf:holdsAccount>      ${userid}
  ${profid} <topaz:organizationType> ''
  ${profid} <topaz:positionType>     ''
  ${profid} <topaz:researchAreas>    ''
  ${profid} <topaz:bio>              ''
  ${profid} <foaf:title>             ''
  ${profid} <topaz:interests>        ''
  ${profid} <topaz:postalAddress>    ''
  ${profid} <topaz:organizationName> ''
  into ${prof};

insert
  ${userid} <profiles:getGender>            ${permall}
  ${userid} <profiles:getOrganizationType>  ${permall}
  ${userid} <profiles:getHomePage>          ${permall}
  ${userid} <profiles:getSurnames>          ${permall}
  ${userid} <profiles:getRealName>          ${permall}
  ${userid} <profiles:getPostalAddress>     ${permall}
  ${userid} <profiles:getPositionType>      ${permall}
  ${userid} <profiles:getInterests>         ${permall}
  ${userid} <profiles:findUsersByProfile>   ${permall}
  ${userid} <profiles:getResearchAreasText> ${permall}
  ${userid} <profiles:getBiography>         ${permall}
  ${userid} <profiles:getBiographyText>     ${permall}
  ${userid} <profiles:getWeblog>            ${permall}
  ${userid} <profiles:setProfile>           ${permall}
  ${userid} <profiles:getDisplayName>       ${permall}
  ${userid} <profiles:getTitle>             ${permall}
  ${userid} <profiles:getPublications>      ${permall}
  ${userid} <profiles:getInterestsText>     ${permall}
  ${userid} <profiles:getOrganizationName>  ${permall}
  ${userid} <profiles:getGivenNames>        ${permall}
  ${userid} <profiles:getCountry>           ${permall}
  ${userid} <profiles:getCity>              ${permall}
  into ${grants};

# To make an admin...
insert
  ${userid} <topaz:hasRoles> ${admin}
  ${admin}  <topaz:role>     'admin'
  into ${users};

Finally, if you are running CAS locally, a corresponding user record is required in the data store for CAS which is usually a PostgreSQL database: 

insert into plos_user (id, loginname, newloginname,
                       password,
                       verified, active, emailverificationtoken,
                       createdon, updatedon, resetpasswordtoken)
               values ('CI8V9NFWLSBK1B9UBZ3S1NJW5NKF54DQ', 'plosadmin@gmail.com', null,
                       '96305d86c8c023c2c2e214e65b99591cd57e1aad86659cf3a7539da2d734cb4fa5908d',
                       true, true, null,
                       '2007-06-08', '2007-06-08', null);

Misc Notes

This command line will help you kill all Java processes on windows. 

ps -W   | grep java   | awk '{print $1}'   | xargs -i taskkill /F /PID {}

Running with no network connection

On windows you may find that you cannot start a service that uses ehcache when you are not connected to the network. This is due to the fact that windows does not have a loopback for multicast connections when the network is unavailable. You might see an error such as: 

ERROR 44:34 MulticastRMICacheManagerPeerProvider> Error starting heartbeat. Error was: error setting options

The solution to this is to install the Microsoft virtual Loopback Adapter. See http://support.microsoft.com/kb/839013 for instructions.

Restoring svn working dir to older version

Subversion 1.5 is looming on the horizon but is not officially here yet. Some dev tools, namely the m2eclipse plugin (v0.9.1+) internally use svn 1.5 which will automatically update dirs with older svn versions! The effect of this renders pre-1.5 svn clients unable to handle those dirs that were svn updated. The remedy is a python script that restores the working copy dir to the desired older version. For example to convert a 1.5 svn working dir to 1.4: 

C:\topaz\src\head>python -m change-svn-wc-format . 1.4

where change-svn-wc-format is a locally installed python script provided by Subversion. Follow the instructions at: SVN 1.5 Release Notes