Mercurial > hg > digilib

annotate doc/src/site/markdown/build-maven.md @ 1658:28df291d4e26

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated documentation. Updated build and install instructions to be simpler and hopefully more clear. Updated @funkyfuture's refactored configuration docs (still lots TODO). Added @funkyfuture's server-setup docu to menu. Renamed non-minified digilib-dbg.html to digilib-dev.html
author Robert Casties <r0bcas7@gmail.com>
date Mon, 20 Nov 2017 21:08:35 +0100
parents 828b6c8b1b19
children a243eb5cc480
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
1 # Building digilib with Maven
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
2
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
3 The best way to get the latest and greatest digilib is using the [git](https://git-scm.com/) version control and the [Maven](http://maven.apache.org/) build tool.
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
4 Git will download the digilib code and Maven will compile, and install the latest digilib version and all required libraries.
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
5
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
6 ## What you need
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
7
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
8 * [git](https://git-scm.com/)
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
9 * [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) (7 or higher)
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
10 * [Maven](http://maven.apache.org/)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
11
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
12 ## Quick developer build and run
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
13
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
14 1. Clone the digilib repository into a directory `digilib`
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
15
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
16 git clone https://github.com/robcast/digilib.git
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
17
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
18 2. Change to the directory
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
19
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
20 cd digilib
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
21
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
22 3. build and run the webapp in the embedded Jetty runtime for development
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
23
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
24 mvn jetty:run-exploded --projects webapp
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
25
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
26 and watch your digilib at http://localhost:8080/digilib.html
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
27
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
28
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
29 ## Developer build
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
30
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
31 If you are developing with digilib it is helpful to check out the source
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
32 code separately so you can keep it around, modify it or change the configuration
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
33 before you deploy.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
34
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
35 To check out the latest source code into the directory `digilib` run
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
36
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
37 git clone https://github.com/robcast/digilib.git
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
38
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
39 and change into the repository directory
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
40
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
41 cd digilib
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
42
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
43 If you want to update your copy of digilib to the latest version at some time in the future
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
44 just run
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
45
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
46 git pull
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
47
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
48 The digilib configuration files are in the sub-directory `webapp/src/main/webapp/WEB-INF/` (see below).
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
49
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
50 To build the resulting source code run
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
51
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
52 mvn package
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
53
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
54 This will create a web application directory `digilib-webapp-2.5-SNAPSHOT`
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
55 and a WAR file `digilib-webapp-2.5-SNAPSHOT-srv3.war` (or similar) in
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
56 the subdirectory `webapp/target/` .
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
57
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
58
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
59 ## Deploying the web application by hand
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
60
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
61 To deploy digilib just copy the web application directory or the WAR file into the `webapp`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
62 directory of the Servlet container.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
63
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
64 Since the URL of your digilib server starts with the name of the web application
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
65 and the name of the web application is derived from the name of the web
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
66 application directory or the WAR file **please rename the web application directory or WAR file
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
67 to `digilib` before you start**
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
68
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
69 Then you should see digilib running at the URL
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
70 http://localhost:8080/digilib/digilib.html
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
71
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
72 If you use the unmodified default configuration you should see the digilib logo
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
73 and other sample images from the `sample-images` directory of the web application.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
74
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
75 For more detailed documentation see the [deployment instructions](install-digilib.html).
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
76
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
77 ## Configuring digilib
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
78
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
79 To change the configuration of digilib just create and edit the file `digilib-config.xml`
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
80 in the web application WEB-INF directory (`webapp/src/main/webapp/WEB-INF/digilib-config.xml`).
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
81 You can copy and rename the sample file `digilib-config.xml.template` to get some default options to start with.
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
82 Please check the [documentation of the configuration options](digilib-config.html).
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
83
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
84 You can see a summary of your running digilib configuration at the URL
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
85 http://localhost:8080/digilib/server/dlConfig.jsp
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
86
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
87 ## Additional Maven build options
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
88
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
89 ### servlet2
1216
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
90
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
91 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6 or later
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
92 and Tomcat version 7 or Jetty version 8 or later to use it.
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
93 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
94 to the Maven command line above.
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents: 1279
diff changeset
95