Nginx configuration example.

#1652.

docs/en/modules/ROOT/pages/faq.adoc

@@ -40,13 +40,12 @@ To ensure only this user has write permission, enter the following command:
 $ chmod -R 755 directory/
 ----
 
-On systems with security sandboxing, you may need to grant permissions to the directory.  For example, on Debian you need to add a SystemD override:
+On systems with security sandboxing, you may need to grant permissions to the directory.  For example, on Debian and Ubuntu you need to add a SystemD override:
 
 ----
 $ sudo systemctl edit tomcat9.service
 [Service]
 ReadWritePaths=/path/to/directory/
-$ sudo systemctl daemon-reload
 $ sudo systemctl restart tomcat9
 ----
 

docs/en/modules/ROOT/pages/installation.adoc

@@ -78,7 +78,7 @@ The IPT has been tested and works well with recent releases of Tomcat 7, 8 or 9.
 --
 TIP: This step is optional, but is recommended to improve security and simplify the upgrade procedure.
 
-Locate the Tomcat configuration directory (usually `/etc/tomcat` or `/etc/tomcat9` on Linux, `C:\Program Files\Apache Software Foundation\Tomcat X.Y\conf` on Windows), and create a file `Catalina/localhost/ipt.xml` (described in the https://tomcat.apache.org/tomcat-8.5-doc/config/context.html#Defining_a_context[Tomcat documentation "Defining a context"]).   For example, on a typical CentOS Linux installation, the file would be `/etc/tomcat/conf/Catalina/localhost/ipt.xml`.
+Locate the Tomcat configuration directory (usually `/etc/tomcat` or `/etc/tomcat9` on Linux, `C:\Program Files\Apache Software Foundation\Tomcat X.Y\conf` on Windows), and create a file `Catalina/localhost/ipt.xml` (described in the https://tomcat.apache.org/tomcat-8.5-doc/config/context.html#Defining_a_context[Tomcat documentation "Defining a context"]). For example, on a typical CentOS Linux installation, the file would be `/etc/tomcat/conf/Catalina/localhost/ipt.xml`. The file should be readable by the Tomcat process.
 
 Define the `IPT_DATA_DIR` parameter within the file — copy and paste the text here, since the case of the letters is important:
 
@@ -89,6 +89,8 @@ Define the `IPT_DATA_DIR` parameter within the file — copy and paste the text
 </Context>
 ----
 
+Ensure the Tomcat server either has permission to create this directory, or create it and then grant read and write permission. See xref:faq.adoc#i-get-the-following-error-the-data-directory-directory-is-not-writable-what-should-i-do[this FAQ entry] if you have errors about write permissions on the data directory.
+
 [NOTE]
 ====
 If this step is not done, the IPT will prompt for a data directory when it is first run.  The location will be stored in a file called `datadir.location` the IPT's base installation directory, e.g. `/var/lib/tomcat/webapps/ipt/WEB-INF/datadir.location`.
@@ -100,15 +102,15 @@ If the data directory location needs to be changed, remove/edit this file and re
 . Deploy the IPT
 +
 --
-Download the latest WAR release of the IPT from the xref:releases.adoc[releases page] and rename it to `ipt.war` (or similar, matching `ipt.xml` from step 2 if used). Copy the `ipt.war` file to the Tomcat webapps folder, and then start Tomcat if it is not already running. You can then invoke the IPT in a web browser running on the same server by using the following URL: http://localhost:8080/ipt
-
-If the installation doesn't start please check the `catalina.out` logfile, and refer to the xref:faq.adoc[FAQ] for help.
+Download the latest WAR release of the IPT from the xref:releases.adoc[releases page] and rename it to `ipt.war` (or similar, matching `ipt.xml` from step 2 if used). Copy the `ipt.war` file to the Tomcat webapps folder, and then start Tomcat if it is not already running.
 --
 
 Successful deployment of the IPT within a servlet container will make the IPT accessible through a web browser at a URL determined by the servlet's name and port, followed by /ipt (e.g., http://server.example.org:8080/ipt). If the installation was successful, the initial IPT setup page will appear in a web browser using the IPT's URL.
 
 Then continue to <<Opening the IPT to the Internet>>.
 
+If the installation doesn't start please check the `catalina.out` logfile, and refer to the xref:faq.adoc[FAQ] for help.
+
 The following screencast also explains how to install the IPT using Tomcat, assuming Tomcat has already been installed.
 
 [.responsive-video]
@@ -170,6 +172,14 @@ The configuration used by `ipt.gbif.org` is shown here as an example.  It uses A
 include::partial$apache-configuration-example.conf[]
 ----
 
+Nginx can also be used as a reverse proxy. An example configuration is below.
+
+// The Nginx configuration example is in a separate file so the translation system can ignore it.
+[source,nginx]
+----
+include::partial$nginx-configuration-example.conf[]
+----
+
 === TLS certificate configuration
 
 For production deployments of the IPT we recommend using a TLS certificate, so information such as logins are secured when accessing the IPT.  The procedure to set this up sometimes depends on your institution's policies, but the free https://letsencrypt.org/[LetsEncrypt] service is a good choice.  They https://certbot.eff.org/instructions[provide instructions] for adding a certificate to Apache, Nginx and many other webservers running on Linux or Windows.

docs/en/modules/ROOT/partials/apache-configuration-example.conf

@@ -19,15 +19,12 @@
     ProxyPass                  /favicon.ico !
     ProxyPass                  /icons !
     ProxyPass                  /media !
-    # Linux packages example
+    # Linux packages or Docker example, or ROOT.war in Tomcat
     ProxyPass                  / http://localhost:8080/
 
     # Alternative: example for an IPT deployed in a servlet container like Tomcat
     #ProxyPass                  /ipt http://localhost:8080/ipt
 
-    # Or deployed as ROOT.war
-    #ProxyPass                  / http://localhost:8080/
-
     # Recommended for HTTPS configurations
     RequestHeader              set X-Forwarded-Proto "https"
     # Typical LetsEncrypt configuration

docs/en/modules/ROOT/partials/nginx-configuration-example.conf

@@ -0,0 +1,39 @@
+server {
+    if ($host = ipt.example.org) {
+        return 302 https://$host$request_uri;
+    }
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name ipt.example.org;
+    return 404;
+}
+
+server {
+    server_name ipt.example.org;
+
+    # Linux packages or Docker example, or ROOT.war in Tomcat
+    location / {
+        proxy_set_header X-Real-IP  $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header Host $host;
+        proxy_pass http://localhost:8080/;
+    }
+
+    # Alternative: example for an IPT deployed in a servlet container like Tomcat
+    #location /ipt/ {
+    #    proxy_set_header X-Real-IP  $remote_addr;
+    #    proxy_set_header X-Forwarded-For $remote_addr;
+    #    proxy_set_header X-Forwarded-Proto https;
+    #    proxy_set_header Host $host;
+    #    proxy_pass http://localhost:8080/ipt/;
+    #}
+
+    # Typical LetsEncrypt configuration
+    listen [::]:443 ssl ipv6only=on;
+    listen 443 ssl;
+    ssl_certificate /etc/letsencrypt/live/ipt.example.org/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/ipt.example.org/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+}