Merge pull request #896 from korpling/document-nginx-reverse-proxy

Document proxy configuration

Author: thomaskrause

docs/user-guide/src/configuration/README.md

@@ -4,8 +4,17 @@ For the desktop version of ANNIS, you most probably don't need to change any of
 If you are installing ANNIS on a server however, you might want to tweak the settings.
 The [Java Properties](http://en.wikipedia.org/w/index.php?title=.properties&oldid=521500688), [TOML](https://toml.io/) and [JSON](http://www.json.org/) file formats are used for different kind of configuration.
 
-ANNIS uses the Spring Boot configuration system and thus it will search for a Java Properties based configuration file named `application.properties` in the current working directory or a `config` sub-directory of the working directory.[^working-dir]
-You can also use the command line argument `--spring.config.location=file:/<location-on-disk>` to specify a specific configuration file.
+ANNIS uses the Spring Boot configuration system and thus it will search for a Java Properties based configuration file named `application.properties` in the current working directory or a `config` sub-directory of the working directory.
+
+<div class="warning">
+Depending on how you start ANNIS, the working directory can be different.
+
+When using `java -jar /path/to/annis-server.jar`, the working directory is the same as the working directory of your current shell.
+If you start ANNIS by treating it like an executable file, e.g. by running `/path/to/annis-server.jar` directly, **the directory containing the jar is used as the working directory** of the application per default.
+</div>
+
+To avoid confusion from where the file is loaded from, you can specify the configuration file location by passing the command line argument `--spring.config.location=file:/<location-on-disk>` when starting ANNIS.
+
 More search paths for configurations files are documented in the [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/2.3.x/reference/html/spring-boot-features.html#boot-features-external-config-application-property-files).
 
 
@@ -46,7 +55,3 @@ spring.datasource.url=jdbc:h2:file:${user.home}/.annis/v4/frontend_data.h2
 ```
 
 Being a Spring Boot application, ANNIS configuration properties also be directly given as [command line argument](https://docs.spring.io/spring-boot/docs/2.3.x/reference/html/spring-boot-features.html#boot-features-external-config-command-line-args).
-
-[^working-dir]: Depending on how you start ANNIS, the working directory can be different.
-When using `java -jar /path/to/annis-server.jar`, the working directory is the same as the working directory of your current shell.
-If you start ANNIS by treating it like an executable file, e.g. by running `/path/to/annis-server.jar` directly, the directory containing the jar is used as the working directory of the application per default.

docs/user-guide/src/installation/server.md

@@ -14,6 +14,43 @@ This will start a REST service on port 5711 and the user interface on port 5712.
 The user interface service will accept requests from all IPs and the embedded REST service only from `localhost`.
 We recommend using a Nginx or Apache server as proxy for the user interface service for production to enable important features like HTTPS encryption.
 
+## Configuring a proxy server
+
+To configure a proxy that uses a different path than `/`, e.g. `https://example.com/annis`, first make sure that the context path is set in the [`application.properties` file](../configuration/).
+
+```
+server.servlet.context-path=/annis
+```
+
+### Nginx
+
+You can configure the location to act as a proxy.
+The `location` must match the context path and end with an `/`.
+The `proxy_pass` directive does not contain the context path, but only specifies the server host and port.
+
+```
+location /annis/ {
+   proxy_pass http://127.0.0.1:5712;
+   # Optimize for Web Sockets
+   # https://www.nginx.com/blog/websocket-nginx/
+   proxy_http_version 1.1;
+   proxy_set_header Upgrade $http_upgrade;
+   proxy_set_header Connection: $connection_upgrade;
+   client_max_body_size 2G;
+}
+```
+
+### Apache
+
+Recent versions of Apache have support for proxying web socket connects, but the `mod_proxy` module must be enabled: <https://httpd.apache.org/docs/2.4/mod/mod_proxy.html>
+
+Then add the following configuration to your site:
+
+```
+ProxyPass /annis/ http://localhost:5712/annis/ upgrade=websocket
+ProxyPassReverse /annis/ http://localhost:5712/annis/
+```
+
 ## Use systemd to run ANNIS as a service
 
 You can create a simple systemd configuration file with the name `annis.service` and save it under one of the valid configuration folders, e.g. `/etc/systemd/system` to register ANNIS as a system service.
@@ -24,7 +61,7 @@ Description=ANNIS corpus search and visualization
 
 [Service]
 Type=simple
-ExecStart=/usr/local/bin/annis-gui-<version>-desktop.jar
+ExecStart=/usr/local/bin/annis-gui-<version>-desktop.jar --spring.config.location=file:/<location-on-disk>
 Environment=""
 User=annis
 Group=annis
@@ -35,6 +72,7 @@ WantedBy=multi-user.target
 ```
 
 This configuration assumes that there is a “annis” user and group on the server.
+The `WorkingDirectory` is not used to locate the `application.properties` file and thus it is best to specify its location with the `--spring.config.location` argument.
 
 You can permanently enable this service by calling
 ```bash