Mercurial > hg > digilib
annotate doc/src/site/markdown/build-maven.md @ 1681:6d5e04a54848
updated server-setup documentation. fixed broken link.
| author | Robert Casties <casties@mpiwg-berlin.mpg.de> |
|---|---|
| date | Wed, 14 Mar 2018 19:43:12 +0100 |
| parents | a243eb5cc480 |
| children |
| 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 | 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. |
| 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 | 8 * [git](https://git-scm.com/) |
| 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 | 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 | 14 1. Clone the digilib repository into a directory `digilib` |
| 15 | |
| 16 git clone https://github.com/robcast/digilib.git | |
| 17 | |
| 18 2. Change to the directory | |
| 19 | |
| 20 cd digilib | |
| 21 | |
| 22 3. build and run the webapp in the embedded Jetty runtime for development | |
| 23 | |
| 24 mvn jetty:run-exploded --projects webapp | |
| 25 | |
| 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 | 37 git clone https://github.com/robcast/digilib.git |
| 38 | |
| 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 | 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 | 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 | 48 The digilib configuration files are in the sub-directory `webapp/src/main/webapp/WEB-INF/` (see below). |
| 49 | |
| 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 | 54 This will create a web application directory `digilib-webapp-2.5-SNAPSHOT` |
| 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 | 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 | 69 Then you should see digilib running at the URL |
| 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 | 75 For more detailed documentation see the [deployment instructions](install-digilib.html). |
| 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 | 79 To change the configuration of digilib just create and edit the file `digilib-config.xml` |
| 80 in the web application WEB-INF directory (`webapp/src/main/webapp/WEB-INF/digilib-config.xml`). | |
| 81 You can copy and rename the sample file `digilib-config.xml.template` to get some default options to start with. | |
| 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 | 85 http://localhost:8080/digilib/server/dlConfig.jsp |
| 86 | |
| 87 ## Additional Maven build options | |
| 88 | |
| 1663 | 89 Some build options have to be activated as Maven profiles with the `-P` command line option |
| 90 when building digilib. For example, to build digilib with the Manifester servlet ("iiif-presentation") | |
| 91 use: | |
| 92 | |
| 93 mvn -Piiif-presentation package | |
| 94 | |
| 95 You can add multiple profiles at the same time if necessary. | |
| 96 | |
| 97 | |
| 1658 | 98 ### 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
|
99 |
| 1658 | 100 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6 or later |
| 101 and Tomcat version 7 or Jetty version 8 or later to use it. | |
| 1663 | 102 |
| 103 `-Pservlet2` builds a servlet with the the old non-Asynchronous Servlet API (2.3). | |
| 104 | |
| 105 This creates a WAR file with the postfix "-srv2". | |
| 106 The build process uses the file `webapp/src/main/webapp/WEB-INF/web-2.4.xml` as `web.xml` file. | |
| 107 | |
| 108 ### servlet3 | |
| 109 | |
| 110 `-Pservlet3` builds digillib with the Asynchronous Servlet API (3.0). This is the default profile, it will be used | |
| 111 if you do not specify any profile. | |
| 112 | |
| 113 This creates a WAR file with the postfix "-srv3". | |
| 114 The build process uses the file `webapp/src/main/webapp/WEB-INF/web-3.0.xml` as `web.xml` file. | |
| 115 | |
| 116 ### iiif-presentation | |
| 117 | |
| 118 `-Piiif-presentation` builds digilib with the "Manifester" servlet for IIIF Presentation API support | |
| 119 (see [digilib IIIF support documentation](iiif-api.html)). | |
| 120 | |
| 121 This creates a WAR file with the postfix "-srv3p". | |
| 122 The build process uses the file `webapp/src/main/webapp/WEB-INF/web-iiif-pres.xml` as `web.xml` file. | |
| 123 | |
| 124 ### text | |
| 1658 | 125 |
| 1663 | 126 `-Ptext` builds digilib with the "Texter" servlet to download plain text or XML files |
| 127 (see [the source](https://github.com/robcast/digilib/tree/master/text)). You have | |
| 128 to add `-Pservlet3` or `-Pservlet2` as well. | |
| 129 | |
| 130 You also have to copy the mapping for the "Texter" servlet from `web-additional.xml` into the `web.xml` file | |
| 131 used by the selected servlet API like `web-3.0.xml`. | |
| 132 | |
| 133 ### pdf | |
| 134 | |
| 135 `-Ppdf` builds digilib with the "PDFCache" servlet to generate and download PDF files from images. | |
| 136 (see [the source](https://github.com/robcast/digilib/tree/master/pdf)). | |
| 137 | |
| 138 You also have to copy the mapping for the "PDFCache" servlet from `web-additional.xml` into the `web.xml` file | |
| 139 used by the selected servlet API like `web-3.0.xml`. | |
| 140 | |
| 141 ## create-sprites | |
| 142 | |
| 143 `-Pcreate-sprites` re-creates the image sprite file (`webapp/src/main/webapp/jquery/img/dl-buttons-full-32-sprite.png`) | |
| 144 from the separate icon image files. This option only needs to be used if you are a developer and you want to | |
| 145 change the icon images. | |
| 146 | |
| 147 ## running tests | |
| 148 | |
| 149 `-DskipTests=false` enables some functional tests. The tests are run as part of the normal build process. | |
| 150 You can also run just the tests with `mvn -DskipTests=false test`. | |
| 151 |