Mercurial > hg > digilib

comparison 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
comparison
equal deleted inserted replaced
1657:fb211930d6e8 1658:28df291d4e26
1 # Building digilib with Maven 1 # Building digilib with Maven
2 2
3 The easiest way to get the latest and greatest digilib is the [Maven](http://maven.apache.org/) build tool. 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 It will download, compile, and install the latest digilib version and all required libraries. 4 Git will download the digilib code and Maven will compile, and install the latest digilib version and all required libraries.
5 5
6 ## What you need 6 ## What you need
7 7
8 * [Java](http://www.java.com/) (1.5 or higher) 8 * [git](https://git-scm.com/)
9 * [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) (7 or higher)
9 * [Maven](http://maven.apache.org/) 10 * [Maven](http://maven.apache.org/)
10 * [Mercurial](http://mercurial.selenic.com/)
11 * A Servlet container like [Tomcat](http://tomcat.apache.org/)
12 or [Jetty](http://www.eclipse.org/jetty/) to run the web application.
13 11
14 ## Quick build 12 ## Quick developer build and run
15 13
16 The fastest way to build the digilib web application is to download the digilib 14 1. Clone the digilib repository into a directory `digilib`
17 project file [pom.xml](https://sourceforge.net/p/digilib/code/ci/default/tree/pom.xml?format=raw) 15
18 (download and save it) and run 16 git clone https://github.com/robcast/digilib.git
19 17
20 mvn scm:bootstrap -N 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
21 27
22 in the same directory as the `pom.xml` file.
23
24 This will create a web application directory `digilib-webapp-2.2-SNAPSHOT`
25 and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar)
26 in the subdirectory `target/checkout/webapp/target/`
27
28 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
29 and Tomcat version 7 or Jetty version 8 or later to use it.
30 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
31 to the Maven command line above.
32 28
33 ## Developer build 29 ## Developer build
34 30
35 If you are developing with digilib it is helpful to check out the source 31 If you are developing with digilib it is helpful to check out the source
36 code separately so you can keep it around, modify it or change the configuration 32 code separately so you can keep it around, modify it or change the configuration
37 before you deploy. 33 before you deploy.
38 34
39 To check out the latest source code into the directory `digilib` run 35 To check out the latest source code into the directory `digilib` run
40 36
41 hg clone http://hg.code.sf.net/p/digilib/code digilib 37 git clone https://github.com/robcast/digilib.git
38
39 and change into the repository directory
42 40
43 The digilib configuration files are now in `digilib/webapp/src/main/webapp/WEB-INF/` 41 cd digilib
44 42
45 If you want to update your copy of digilib to the latest version at some time in the future 43 If you want to update your copy of digilib to the latest version at some time in the future
46 just run 44 just run
47 45
48 hg pull 46 git pull
49 hg up
50
51 in the `digilib` directory.
52 47
53 To build the resulting source code, change into the `digilib` 48 The digilib configuration files are in the sub-directory `webapp/src/main/webapp/WEB-INF/` (see below).
54 directory you checked out above and run 49
50 To build the resulting source code run
55 51
56 mvn package 52 mvn package
57 53
58 This will create a web application directory `digilib-webapp-2.2-SNAPSHOT` 54 This will create a web application directory `digilib-webapp-2.5-SNAPSHOT`
59 and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar) in 55 and a WAR file `digilib-webapp-2.5-SNAPSHOT-srv3.war` (or similar) in
60 the subdirectory `webapp/target/` . 56 the subdirectory `webapp/target/` .
61 57
62 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
63 and Tomcat version 7 or Jetty version 8 or later to use it.
64 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
65 to the Maven command line above.
66 58
67 ## Deploying the web application by hand 59 ## Deploying the web application by hand
68 60
69 To deploy digilib just copy the web application directory or the WAR file into the `webapp` 61 To deploy digilib just copy the web application directory or the WAR file into the `webapp`
70 directory of the Servlet container. 62 directory of the Servlet container.
71 63
72 Since the URL of your digilib server starts with the name of the web application 64 Since the URL of your digilib server starts with the name of the web application
73 and the name of the web application is derived from the name of the web 65 and the name of the web application is derived from the name of the web
74 application directory or the WAR file **please rename the web application directory or WAR file 66 application directory or the WAR file **please rename the web application directory or WAR file
75 to `digitallibrary` before you start** 67 to `digilib` before you start**
76 68
77 Then you should see your digilib running at the URL 69 Then you should see digilib running at the URL
78 [http://localhost:8080/digitallibrary/jquery/digilib.html](http://localhost:8080/digitallibrary/jquery/digilib.html) 70 http://localhost:8080/digilib/digilib.html
79 71
80 If you use the unmodified default configuration you should see the digilib logo 72 If you use the unmodified default configuration you should see the digilib logo
81 and other sample images from the `sample-images` directory of the web application. 73 and other sample images from the `sample-images` directory of the web application.
82 74
75 For more detailed documentation see the [deployment instructions](install-digilib.html).
76
83 ## Configuring digilib 77 ## Configuring digilib
84 78
85 To change the configuration of digilib just edit the file `digilib-config.xml` 79 To change the configuration of digilib just create and edit the file `digilib-config.xml`
86 in the web application directory (`digitallibrary/WEB-INF/digilib-config.xml`). 80 in the web application WEB-INF directory (`webapp/src/main/webapp/WEB-INF/digilib-config.xml`).
87 Documentation of the configuration options is [here](digilib-config.html). 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).
88 83
89 You can see a summary of your running digilib configuration at the URL 84 You can see a summary of your running digilib configuration at the URL
90 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp) 85 http://localhost:8080/digilib/server/dlConfig.jsp
91 86
87 ## Additional Maven build options
88
89 ### servlet2
90
91 Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6 or later
92 and Tomcat version 7 or Jetty version 8 or later to use it.
93 If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
94 to the Maven command line above.
95