Mercurial > hg > digilib

annotate doc/src/site/markdown/server-setup.md @ 1714:d497eb11141c default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated travis-ci config for automatic WAR releases.
author Robert Casties <casties@mpiwg-berlin.mpg.de>
date Mon, 18 Feb 2019 20:49:15 +0100
parents 79b95ce5d315
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1681
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
1 # Server setup for digilib
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
2
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
3 There are a variety of ways to deploy digilib on different server configurations for production sites.
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
4
1681
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
5 Here are some examples and tips.
1658
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
6
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
7 ## nginx as proxy
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
8
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
9 This is an example configuration for `nginx` as a proxy for a single instance
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
10 of digilib (listening on port `8080`) that handles transport encryption and
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
11 restricts access to sensitive data to the gateway of a local network
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
12 (`1.2.3.4`).
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
13
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
14 ```nginx
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
15 server {
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
16 listen 443 ssl http2;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
17 listen [::]:443 ssl http2;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
18 server_name digilib.example.org;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
19
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
20 # this certificate chain shall *not* include the root certificate:
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
21 ssl_certificate /etc/ssl/certs/digilib.example.org.pem;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
22 ssl_certificate_key /etc/ssl/private/digilib.example.org.key;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
23
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
24 include /etc/nginx/proxy_params;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
25
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
26 location ~* .*/(dlConfig|dlRequest).jsp$ {
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
27 allow 1.2.3.4;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
28 deny all;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
29 proxy_pass http://localhost:8080;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
30 }
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
31
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
32 location / {
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
33 proxy_pass http://localhost:8080;
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
34 }
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
35 }
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
36 ```
28df291d4e26 Updated documentation.
Robert Casties <r0bcas7@gmail.com>
parents:
diff changeset
37
1699
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
38 Please check the [nginx documentation](nginx.org/en/docs/).
1681
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
39
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
40 ## Apache as proxy and load-balancer
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
41
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
42 This is an example configuration for [Apache](https://httpd.apache.org/) as a proxy and load balancer for two instances of
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
43 digilib (one running on localhost, port 8080 and another on otherserver, port 8080), using SSL and http/2:
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
44
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
45 ```
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
46 <VirtualHost *:443>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
47 # HTTP/2 protocol (Apache 2.4.29 and later)
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
48 Protocols h2 http/1.1
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
49 ServerName digilib.example.com
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
50 SSLCertificateFile /etc/ssl/private/digilib-cert.pem
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
51 SSLCertificateKeyFile /etc/ssl/private/digilib-key.pem
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
52 SSLEngine on
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
53
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
54 DocumentRoot /var/www
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
55 <Directory />
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
56 Options FollowSymLinks
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
57 AllowOverride None
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
58 </Directory>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
59 <Directory /var/www/>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
60 Options Indexes FollowSymLinks MultiViews
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
61 AllowOverride None
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
62 Order allow,deny
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
63 allow from all
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
64 </Directory>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
65
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
66 ErrorLog ${APACHE_LOG_DIR}/digilib-ssl-error.log
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
67 LogLevel warn
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
68 CustomLog ${APACHE_LOG_DIR}/digilib-ssl-access.log combined
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
69
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
70 # do not forward-proxy!
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
71 ProxyRequests off
1698
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
72 # set proxy headers
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
73 ProxyPreserveHost On
1681
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
74 RequestHeader set X-Forwarded-Proto "https"
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
75 # digilib instances
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
76 <Proxy balancer://digilibs>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
77 BalancerMember http://127.0.0.1:8080
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
78 BalancerMember http://otherserver.example.com:8080
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
79 </Proxy>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
80 # balance by busy-ness
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
81 ProxyPass /digitallibrary balancer://digilibs/digitallibrary lbmethod=bybusyness
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
82 ProxyPassReverse /digitallibrary balancer://digilibs/digitallibrary
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
83
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
84 # balancer-manager frontend (be careful!)
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
85 <Location /balancer-manager>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
86 SetHandler balancer-manager
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
87 Require host localhost
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
88 </Location>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
89 </VirtualHost>
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
90 ```
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
91
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
92 ## Jetty behind a proxy
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
93
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
94 When you are using [Jetty](https://www.eclipse.org/jetty/) as servlet container behind an Apache or nginx proxy
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
95 then you should make sure that Jetty processes the `X-Forwarded-*` headers from the proxy server to derive the
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
96 correct request URL for the servlets.
6d5e04a54848 updated server-setup documentation. fixed broken link.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1658
diff changeset
97
1698
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
98 Please see [this information for Jetty 9.4](http://www.eclipse.org/jetty/documentation/9.4.x/configuring-connectors.html#_proxy_load_balancer_connection_configuration)
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
99 or [this information for Jetty 8 and earlier versions](https://wiki.eclipse.org/Jetty/Tutorial/Apache#Configuring_mod_proxy_http).
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
100
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
101 ## Tomcat behind a proxy
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
102
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
103 When you are using [Tomcat](https://tomcat.apache.org) as a servlet container behind an Apache or nginx proxy then
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
104 you should make sure that Tomcat processes the `X-Forwarded-*` headers from the proxy server to derive the
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
105 correct request URL for the servlets.
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
106
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
107 Please see the Tomcat documentation about the [Remote IP Valve](https://tomcat.apache.org/tomcat-9.0-doc/config/valve.html#Remote_IP_Valve).
1699
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
108 You basically need to add the following XML tag with your proxy's IP numbers to the `Host` tag of your `server.xml` file
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
109 and make sure `ProxyPreserveHost` is set to `on`:
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
110
1698
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
111 ```
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
112 <Valve className="org.apache.catalina.valves.RemoteIpValve"
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
113 internalProxies="127\.0\.0\.1|123\.45\.67\.89"
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
114 remoteIpHeader="x-forwarded-for"
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
115 proxiesHeader="x-forwarded-by"
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
116 protocolHeader="x-forwarded-proto" />
7e4396e467de Add documentation about running Tomcat behind a proxy.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1681
diff changeset
117 ```
1699
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
118
79b95ce5d315 Small fix to docs.
Robert Casties <casties@mpiwg-berlin.mpg.de>
parents: 1698
diff changeset
119