Expand installation instructions in README.md

[danielgrant]

The current README.md assumes a certain degree of knowledge around the building and deployment of Java web applications (i.e. .war's).

These instructions should be expanded to include compilation of elucidate-server itself, as well as additional steps to get up and running, for non-technical users or users not familiar with Java.

[tyy0402]

Thanks a lot!

[jpadfield]

Hi,

I was hoping to be able to try this annotation server out, but it has not been going well, I do not use Java very much but I am normally enable to follow instructions :-)

I have managed to install the stated prerequisites and build each of the four elucidate-**** systems using the Maven command and everything has worked well and I have created an Annotation.war file.

Now I can deploy the war file, but it fails to do anything, and gives an error when I try to start it, so I am assuming I need to do more before it can start up.

The configuration section indicates that the "elucidate-server.properties" files needs to be referenced but it is very unclear where or how?

For the database, there are a huge number of scripts, are they all required, are they needed in a specific order, has anyone already combined then into a single file in the correct order?

Does the "properties" file and the database scripts need to be sorted before the server is built?

It would be great to be able to potential use this server.

Thanks

Joe

[tyy0402]

Hi, Joe

I am a beginner of Java and I even do not know how to create war files. I cannot figure out how to use elucidate-server, so I changed to another server. Actually, I tried all annotation servers and used the one which can be worked on my computer(Windows) and cloud server(Linux).

Hope it can help you.

[danielgrant]

Hi @jpadfield, @tyy0402,

I understand your concerns here, there are improvements we can and are making to make this a bit easier for the non-technical / non-Java users out there to install and get up and running.

With regards to elucidate-server.properties, the location of this file needs to be passed to the JVM using a -D parameter. This is just a parameter to the JVM during startup that can then be read by the application and used to initialise it. If you're using Tomcat for example, you can modify (or create it if it doesn't exist) this file in your Tomcat installation:

For Windows users:

/bin/setenv.bat

and add:

set "JAVA_OPTS=%JAVA_OPTS% -Delucidate.server.properties=file:C:/path/to/elucidate-server.properties"

For Linux users

/bin/setenv.bat

and add:

export "JAVA_OPTS=%JAVA_OPTS% -Delucidate.server.properties=file:/path/to/elucidate-server.properties"

The setenv.[sh|bat] file is automatically read by Tomcat's standard startup.[sh|bat].

For the database, all the scripts do need to be run and the following order should satisfy the various constraints and allow everything to be created without error:

1. annotations.sql
2. group_roles/annotations_role.sql
3. login_roles/annotations_user.sql
4. tables/annotation_collection.sql
5. tables/annotation.sql
6. tables/annotation_body.sql
7. tables/annotation_target.sql
8. tables/annotation_agent.sql
9. tables/annotation_agent_*.sql
10. tables/annotation_history.sql
11. tables/annotation_selector.sql
12. tables/annotation_temporal.sql
13. permissions/*.sql
14. functions/*.sql
15. views/*.sql

We're currently working to containerise Elucidate and automate the database installation and subsequent database upgrades, this should allow Elucidate to be deployed much quicker in the future. I'll also look to start including pre-compiled binaries of Elucidate with future releases, to save users having to compile it themselves. Bear with us!

Thanks, Daniel.

[jpadfield]

@danielgrant Thank you very much for your response, hopefully that will be enough to get me going :-)

I fully understand that these things can be complicated and its is great that it is available for use, thanks.

I have gone through a number of steps but once I have things working, if I ever manage to come up with a clear description of what I have done I can post it if it is useful

Also thanks @tyy0402 for your response.

Joe

[jpadfield]

@danielgrant

For the scripts, from your list it was easy to make:

#!/bin/bash

PATH="/usr/local/elucidate/elucidate-db-scripts"
OUT="$PATH/out.sql"

/bin/cat $PATH/annotations.sql >> $OUT
/bin/cat $PATH/group_roles/annotations_role.sql >> $OUT
/bin/cat $PATH/login_roles/annotations_user.sql >> $OUT
/bin/cat $PATH/tables/annotation_collection.sql >> $OUT
/bin/cat $PATH/tables/annotation.sql >> $OUT
/bin/cat $PATH/tables/annotation_body.sql >> $OUT
/bin/cat $PATH/tables/annotation_target.sql >> $OUT
/bin/cat $PATH/tables/annotation_agent.sql >> $OUT
/bin/cat $PATH/tables/annotation_agent_*.sql >> $OUT
/bin/cat $PATH/tables/annotation_history.sql >> $OUT
/bin/cat $PATH/tables/annotation_selector.sql >> $OUT
/bin/cat $PATH/tables/annotation_temporal.sql >> $OUT
/bin/cat $PATH/permissions/*.sql >> $OUT
/bin/cat $PATH/functions/*.sql >> $OUT
/bin/cat $PATH/views/*.sql >> $OUT

[jpadfield]

@danielgrant I have tried running the combined SQL and unfortunately is does not seem to be happy. Most of it runs fine and it does run to the end, but there are a lot of errors relating to "types" and "functions" that do not exist.

There are also a few syntax errors and one related to the fact that encrypted passwords are no longer supported.

I am happy to do some more testing or make some changes, if you have time : -)

Thanks

Joe

[jpadfield]

Most of the errors were related to the user issue at the start - removing the "UNENCRYPTED" in front of the password allowed it all to run - just one syntax error, which I am just looking at.

[garyttierney]

Hi @jpadfield, there is a syntax error in one of the SQL scripts that is fixed and merged, but yet to be released. It's likely the one here that you need to fix: https://github.com/dlcs/elucidate-server/commit/08f8863ca4edf4217f97684777c2b7746d1a176a.

[jpadfield]

Yes that's the one, in the file: /views/annotation_collection_get.sql line 17:

ALTER TABLE public.annotation_collection_getOWNER TO postgres;' needs to be edited to: ALTER TABLE public.annotation_collection_get OWNER TO postgres;

[jpadfield]

Hi, I hope I am almost there now, but there still seem to be some issues deploying the war file. I seem to be getting a lot of errors relating to creating beans relating to oaAnnotation... which I assume is related to the settings in the "elucidate-servers.properties" file. (I also seem to have some errors relating to log4j as well but they do not seem to be breaking things)

The tomcat log is quite log but starts with the following:

05-Jul-2018 11:23:29.881 INFO [http-nio-8080-exec-1] org.apache.catalina.core.ApplicationContext.log No Spring WebApplicationInitializer types detected on classpath
05-Jul-2018 11:23:29.962 INFO [http-nio-8080-exec-1] org.apache.catalina.core.ApplicationContext.log Initializing Spring root WebApplicationContext
05-Jul-2018 11:23:32.545 SEVERE [http-nio-8080-exec-1] org.apache.catalina.core.StandardContext.listenerStart Exception sending context initialized event to listener instance of class [org.springframework.web.context.ContextLoaderListener]
 org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'oaAnnotationBulkUpdateController' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/web/controller/oa/OAAnnotationBatchController.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'oaAnnotationBulkUpdateServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/batch/impl/OAAnnotationBatchUpdateServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'oaAnnotationServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/query/impl/OAAnnotationServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 1: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'oaAnnotationServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/query/impl/OAAnnotationServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 1: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'oaAnnotationBulkUpdateServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/batch/impl/OAAnnotationBatchUpdateServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'oaAnnotationServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/query/impl/OAAnnotationServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 1: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'oaAnnotationServiceImpl' defined in file [/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/classes/com/digirati/elucidate/service/query/impl/OAAnnotationServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 1: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'iriBuilderServiceImpl' defined in URL [jar:file:/home/joe/Software/apache-tomcat-9.0.10/webapps/annotation/WEB-INF/lib/elucidate-common-lib-1.4.2.jar!/com/digirati/elucidate/common/service/impl/IRIBuilderServiceImpl.class]: Unsatisfied dependency expressed through constructor parameter 2: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""; nested exception is org.springframework.beans.TypeMismatchException: Failed to convert value of type [java.lang.String] to required type [int]; nested exception is java.lang.NumberFormatException: For input string: ""

[garyttierney]

Hi @jpadfield,

You'll want to change the base.scheme, base.path, base.port, and base.host parameters in elucidate-server.properties to point at your own web-server.

E.g.,

base.scheme=http
base.host=localhost
base.port=8080
base.path=/annotation

[jpadfield]

@garyttierney - the war file now deploys :-) The root page /annotation returns a 404, but I will now explore how to actual use the server. Thanks

[atomotic]

i got the server deployed with docker but i'm not able to figure how to use. /annotation/ is 404 for me too

elucidate_1  | 2018-08-08 09:10:04.273 [http-nio-8080-exec-3] [DEBUG] CommonsRequestLoggingFilter - Before request [uri=/annotation/]
elucidate_1  | 2018-08-08 09:10:04.274 [http-nio-8080-exec-3] [DEBUG] DispatcherServlet - DispatcherServlet with name 'annotation' processing GET request for [/annotation/]
elucidate_1  | 2018-08-08 09:10:04.274 [http-nio-8080-exec-3] [DEBUG] RequestMappingHandlerMapping - Looking up handler method for path /
elucidate_1  | 2018-08-08 09:10:04.277 [http-nio-8080-exec-3] [DEBUG] RequestMappingHandlerMapping - Did not find handler method for [/]
elucidate_1  | 2018-08-08 09:10:04.293 [http-nio-8080-exec-3] [WARN] PageNotFound - No mapping found for HTTP request with URI [/annotation/] in DispatcherServlet with name 'annotation'
elucidate_1  | 2018-08-08 09:10:04.294 [http-nio-8080-exec-3] [DEBUG] DispatcherServlet - Successfully completed request
elucidate_1  | 2018-08-08 09:10:04.295 [http-nio-8080-exec-3] [DEBUG] CommonsRequestLoggingFilter - After request [uri=/annotation/]

[danielgrant]

Hi @atomotic,

You can locate usage instructions in USAGE.md, but to summarise:

There is nothing available under the root path / (or /annotation if you're using the default context path). All requests must be made under either the /annotation/w3c or /annotation/oa endpoint. By default, there won't be anything under these paths, so you'll probably want to start by creating a container and adding some annotations.

Cheers, Daniel.