Wiki source code of HTTP Reverse Proxy for XWiki
Last modified by Eleni Cojocariu on 2026/09/11 22:52
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | XWiki runs inside a [[Servlet Container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] that answers plain ##HTTP##, by default on port ##8080##. An HTTP reverse proxy placed in front of it serves the wiki on the standard ##80## and ##443## ports, terminates ##HTTPS##, and becomes the single place where access control, logging and rate limiting apply, so the container itself never has to be reachable by readers. | ||
| 2 | |||
| 3 | {{plantuml}} | ||
| 4 | @startuml | ||
| 5 | !theme bluegray | ||
| 6 | skinparam componentStyle rectangle | ||
| 7 | left to right direction | ||
| 8 | |||
| 9 | actor "Reader" as USER | ||
| 10 | |||
| 11 | component "**Reverse proxy**\nApache HTTP Server or NginX\nterminates HTTPS, applies access control" as PROXY | ||
| 12 | component "**Servlet container**\nTomcat or Jetty\nreachable on the loopback interface only" as CONTAINER | ||
| 13 | component "**XWiki**\nreads the forwarded headers and\nbuilds URLs for the public address" as XWIKI | ||
| 14 | |||
| 15 | USER --> PROXY : HTTPS, port 443 | ||
| 16 | PROXY --> CONTAINER : HTTP, port 8080\nHost, X-Forwarded-For, X-Forwarded-Proto | ||
| 17 | CONTAINER --> XWIKI | ||
| 18 | XWIKI --> PROXY : pages and redirects carrying\nthe public HTTPS address | ||
| 19 | PROXY --> USER : answer, over HTTPS | ||
| 20 | @enduml | ||
| 21 | {{/plantuml}} | ||
| 22 | |||
| 23 | Two things change once XWiki stops receiving requests directly. The proxy becomes the only source of truth about the request the reader actually made: XWiki reads the ##Forwarded##, ##X-Forwarded-Proto##, ##X-Forwarded-Host## and ##X-Forwarded-For## headers itself and builds its links from them, so the proxy has to send them and, just as importantly, has to drop the ones a client sent, otherwise a visitor can make the wiki emit links for any address. Telling the Servlet Container to trust the same headers is worth doing as well, so that its own view of the request matches: the scheme returned to code that asks the container rather than XWiki, and the client address in its access log (see [[Configure Tomcat to Find Proxy Headers>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]]). And the ##xwiki.home## property of the [[##xwiki.cfg## configuration file>>doc:documentation.xs.admin.configuration.WebHome]] has to hold the public base address, because URLs built outside a request, in notification mails, for instance, have no forwarded headers to derive it from. When it is set, it also wins over the forwarded headers for the main wiki's own URLs, so an address left over from an earlier deployment quietly overrides a correctly configured proxy. | ||
| 24 | |||
| 25 | Both Apache HTTP Server and NginX are used in front of XWiki; the choice usually follows whichever of them is already installed and administered. | ||
| 26 | |||
| 27 | * [[Apache Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]]: the Apache directives a wiki needs, and the procedures that set them up on Linux, on Windows and for ##HTTPS##. | ||
| 28 | * [[NginX Server Key Configurations>>doc:documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]]: the equivalent NginX directives, and the procedures that set them up on Linux, on Windows and for ##HTTPS##. | ||
| 29 | * [[Reverse Proxy and SSH Tunneling>>doc:documentation.xs.admin.installation.http-reverse-proxy.ssh-tunneling.WebHome]]: reaching a wiki that runs on a machine with no public address, through a remote server. |
