Mercurial > hg > digilib

annotate doc/src/site/markdown/build-maven.md @ 1273:30ec52034355

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added some forgotten docs.
author robcast
date Fri, 31 Jan 2014 12:26:08 +0100
parents bd7dfa8b164e
children 828b6c8b1b19
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
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
3 The easiest way to get the latest and greatest digilib is the [Maven](http://maven.apache.org/) build tool.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
4 It will download, compile, and install the latest digilib version and all required libraries.
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
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
8 * [Java](http://www.java.com/) (1.5 or higher)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
9 * [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
10 * [Mercurial](http://mercurial.selenic.com/)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
11 * A Servlet container like [Tomcat](http://tomcat.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
12 or [Jetty](http://www.eclipse.org/jetty/) to run 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
13
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
14 ## Quick build
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
15
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
16 The fastest way to build the digilib web application is to download the digilib
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
17 project file [pom.xml](http://hg.berlios.de/repos/digilib/raw-file/tip/pom.xml)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
18 (download and save it) and run
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
19
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
20 mvn scm:bootstrap -N
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
21
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
22 in the same directory as the `pom.xml` file.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
23
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
24 This will create a web application directory `digilib-webapp-2.2-SNAPSHOT`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
25 and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
26 in the subdirectory `target/checkout/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
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 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
29 and Tomcat version 7 or Jetty version 8 or later to use it.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
30 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
31 to the Maven command line above.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
32
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
33 ## 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
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 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
36 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
37 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
38
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
39 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
40
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
41 hg clone http://hg.berlios.de/repos/digilib
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 The digilib configuration files are now in `digilib/webapp/src/main/webapp/WEB-INF/`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
44
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
45 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
46 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
47
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
48 hg pull
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
49 hg up
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
50
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
51 in the `digilib` directory.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
52
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
53 To build the resulting source code, change into the `digilib`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
54 directory you checked out above and run
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
55
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
56 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
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 This will create a web application directory `digilib-webapp-2.2-SNAPSHOT`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
59 and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar) in
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
60 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
61
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
62 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
63 and Tomcat version 7 or Jetty version 8 or later to use it.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
64 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
65 to the Maven command line above.
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
66
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
67 ## 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
68
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
69 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
70 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
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 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
73 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
74 application directory or the WAR file **please rename the web application directory or WAR file
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
75 to `digitallibrary` before you start**
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
76
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
77 Then you should see your digilib running at the URL
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
78 [http://localhost:8080/digitallibrary/jquery/digilib.html](http://localhost:8080/digitallibrary/jquery/digilib.html)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
79
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
80 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
81 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
82
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
83 ## 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
84
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
85 To change the configuration of digilib just edit the file `digilib-config.xml`
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
86 in the web application directory (`digitallibrary/WEB-INF/digilib-config.xml`).
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
87 Documentation of the configuration options is [here](digilib-config.html).
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
88
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
89 You can see a summary of your running digilib configuration at the URL
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
90 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)
bd7dfa8b164e move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
robcast
parents:
diff changeset
91