From a053ae4a0d881c870c81af4ad05e578dfe7e89e3 Mon Sep 17 00:00:00 2001 From: Thomas Krause Date: Fri, 6 Jun 2025 11:26:08 +0200 Subject: [PATCH] Document proxy configuration and warn more explicit about the working directory issues and application.properties --- docs/user-guide/src/configuration/README.md | 17 +++++---- docs/user-guide/src/installation/server.md | 40 ++++++++++++++++++++- 2 files changed, 50 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/src/configuration/README.md b/docs/user-guide/src/configuration/README.md index 938a9ef6c1..66808031f7 100644 --- a/docs/user-guide/src/configuration/README.md +++ b/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:/` 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. + +
+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. +
+ +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:/` 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. \ No newline at end of file diff --git a/docs/user-guide/src/installation/server.md b/docs/user-guide/src/installation/server.md index 7ccdd31fa1..f7352fe624 100644 --- a/docs/user-guide/src/installation/server.md +++ b/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: + +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--desktop.jar +ExecStart=/usr/local/bin/annis-gui--desktop.jar --spring.config.location=file:/ 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