Wiki source code of HTTP Reverse Proxy for XWiki
Last modified by Eleni Cojocariu on 2026/11/17 17:14
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 | ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under | ||
| 7 | ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm. | ||
| 8 | skinparam activity { | ||
| 9 | BackgroundColor #0568AE | ||
| 10 | BorderColor #034873 | ||
| 11 | FontColor #FFFFFF | ||
| 12 | StartColor #04538B | ||
| 13 | EndColor #04538B | ||
| 14 | BarColor #5A5A5A | ||
| 15 | ' Diamonds are blue with white text, not light with dark text: a labelled | ||
| 16 | ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from | ||
| 17 | ' FontColor above, so a light fill draws that one box white on white, and no | ||
| 18 | ' selector reaches it without reaching the decision diamonds too. | ||
| 19 | DiamondBackgroundColor #0568AE | ||
| 20 | DiamondBorderColor #034873 | ||
| 21 | DiamondFontColor #FFFFFF | ||
| 22 | } | ||
| 23 | skinparam state { | ||
| 24 | BackgroundColor #0568AE | ||
| 25 | BorderColor #034873 | ||
| 26 | FontColor #FFFFFF | ||
| 27 | AttributeFontColor #FFFFFF | ||
| 28 | StartColor #04538B | ||
| 29 | EndColor #04538B | ||
| 30 | } | ||
| 31 | skinparam class { | ||
| 32 | BackgroundColor #0568AE | ||
| 33 | BorderColor #034873 | ||
| 34 | FontColor #FFFFFF | ||
| 35 | HeaderBackgroundColor #0568AE | ||
| 36 | AttributeFontColor #FFFFFF | ||
| 37 | StereotypeFontColor #262626 | ||
| 38 | } | ||
| 39 | skinparam object { | ||
| 40 | BackgroundColor #0568AE | ||
| 41 | BorderColor #034873 | ||
| 42 | FontColor #FFFFFF | ||
| 43 | AttributeFontColor #FFFFFF | ||
| 44 | StereotypeFontColor #262626 | ||
| 45 | } | ||
| 46 | skinparam participant { | ||
| 47 | BackgroundColor #0568AE | ||
| 48 | BorderColor #034873 | ||
| 49 | FontColor #FFFFFF | ||
| 50 | } | ||
| 51 | skinparam actor { | ||
| 52 | BackgroundColor #F5F5F5 | ||
| 53 | BorderColor #5A5A5A | ||
| 54 | FontColor #262626 | ||
| 55 | } | ||
| 56 | skinparam component { | ||
| 57 | BackgroundColor #0568AE | ||
| 58 | BorderColor #034873 | ||
| 59 | FontColor #FFFFFF | ||
| 60 | } | ||
| 61 | skinparam collections { | ||
| 62 | BackgroundColor #0568AE | ||
| 63 | BorderColor #034873 | ||
| 64 | FontColor #FFFFFF | ||
| 65 | } | ||
| 66 | skinparam queue { | ||
| 67 | BackgroundColor #0568AE | ||
| 68 | BorderColor #034873 | ||
| 69 | FontColor #FFFFFF | ||
| 70 | } | ||
| 71 | skinparam stack { | ||
| 72 | BackgroundColor #0568AE | ||
| 73 | BorderColor #034873 | ||
| 74 | FontColor #FFFFFF | ||
| 75 | } | ||
| 76 | ' database, control, entity, boundary and interface draw their label beside or | ||
| 77 | ' under the icon, on the page, in some diagram types: their text stays dark. | ||
| 78 | skinparam database { | ||
| 79 | BackgroundColor #F5F5F5 | ||
| 80 | BorderColor #5A5A5A | ||
| 81 | FontColor #262626 | ||
| 82 | } | ||
| 83 | skinparam control { | ||
| 84 | BackgroundColor #0568AE | ||
| 85 | BorderColor #034873 | ||
| 86 | FontColor #262626 | ||
| 87 | } | ||
| 88 | skinparam entity { | ||
| 89 | BackgroundColor #0568AE | ||
| 90 | BorderColor #034873 | ||
| 91 | FontColor #262626 | ||
| 92 | } | ||
| 93 | skinparam boundary { | ||
| 94 | BackgroundColor #0568AE | ||
| 95 | BorderColor #034873 | ||
| 96 | FontColor #262626 | ||
| 97 | } | ||
| 98 | skinparam usecase { | ||
| 99 | BackgroundColor #0568AE | ||
| 100 | BorderColor #034873 | ||
| 101 | FontColor #FFFFFF | ||
| 102 | StereotypeFontColor #FFFFFF | ||
| 103 | } | ||
| 104 | skinparam card { | ||
| 105 | BackgroundColor #04538B | ||
| 106 | BorderColor #034873 | ||
| 107 | FontColor #FFFFFF | ||
| 108 | } | ||
| 109 | skinparam note { | ||
| 110 | BackgroundColor #04538B | ||
| 111 | BorderColor #034873 | ||
| 112 | FontColor #FFFFFF | ||
| 113 | } | ||
| 114 | skinparam storage { | ||
| 115 | BackgroundColor #8A4A00 | ||
| 116 | BorderColor #8A4A00 | ||
| 117 | FontColor #FFFFFF | ||
| 118 | } | ||
| 119 | skinparam agent { | ||
| 120 | BackgroundColor #8A4A00 | ||
| 121 | BorderColor #8A4A00 | ||
| 122 | FontColor #FFFFFF | ||
| 123 | } | ||
| 124 | skinparam interface { | ||
| 125 | BackgroundColor #A62222 | ||
| 126 | BorderColor #A62222 | ||
| 127 | FontColor #262626 | ||
| 128 | } | ||
| 129 | skinparam node { | ||
| 130 | BackgroundColor #F5F5F5 | ||
| 131 | BorderColor #5A5A5A | ||
| 132 | FontColor #262626 | ||
| 133 | } | ||
| 134 | skinparam cloud { | ||
| 135 | BackgroundColor #F5F5F5 | ||
| 136 | BorderColor #5A5A5A | ||
| 137 | FontColor #262626 | ||
| 138 | } | ||
| 139 | skinparam artifact { | ||
| 140 | BackgroundColor #F5F5F5 | ||
| 141 | BorderColor #5A5A5A | ||
| 142 | FontColor #262626 | ||
| 143 | } | ||
| 144 | skinparam file { | ||
| 145 | BackgroundColor #F5F5F5 | ||
| 146 | BorderColor #5A5A5A | ||
| 147 | FontColor #262626 | ||
| 148 | } | ||
| 149 | skinparam rectangle { | ||
| 150 | BackgroundColor #FFFFFF | ||
| 151 | BorderColor #5A5A5A | ||
| 152 | FontColor #262626 | ||
| 153 | StereotypeFontColor #0568AE | ||
| 154 | } | ||
| 155 | skinparam folder { | ||
| 156 | BackgroundColor #F5F5F5 | ||
| 157 | BorderColor #8A4A00 | ||
| 158 | FontColor #8A4A00 | ||
| 159 | } | ||
| 160 | skinparam frame { | ||
| 161 | BackgroundColor #F5F5F5 | ||
| 162 | BorderColor #04538B | ||
| 163 | FontColor #04538B | ||
| 164 | } | ||
| 165 | skinparam package { | ||
| 166 | BackgroundColor #FFFFFF | ||
| 167 | BorderColor #0568AE | ||
| 168 | FontColor #262626 | ||
| 169 | } | ||
| 170 | skinparam partition { | ||
| 171 | BackgroundColor #FFFFFF | ||
| 172 | BorderColor #0568AE | ||
| 173 | FontColor #0568AE | ||
| 174 | } | ||
| 175 | skinparam swimlane { | ||
| 176 | BorderColor #0568AE | ||
| 177 | TitleBackgroundColor #F5F5F5 | ||
| 178 | TitleFontColor #0568AE | ||
| 179 | } | ||
| 180 | skinparam sequence { | ||
| 181 | BoxBackgroundColor #F5F5F5 | ||
| 182 | BoxBorderColor #5A5A5A | ||
| 183 | BoxFontColor #262626 | ||
| 184 | DelayFontColor #262626 | ||
| 185 | GroupBorderColor #5A5A5A | ||
| 186 | GroupFontColor #262626 | ||
| 187 | LifeLineBorderColor #5A5A5A | ||
| 188 | LifeLineBackgroundColor #F5F5F5 | ||
| 189 | TitleFontColor #0568AE | ||
| 190 | StartColor #0568AE | ||
| 191 | EndColor #0568AE | ||
| 192 | BorderColor #0568AE | ||
| 193 | } | ||
| 194 | skinparam arrow { | ||
| 195 | Color #0568AE | ||
| 196 | FontColor #262626 | ||
| 197 | } | ||
| 198 | skinparam legend { | ||
| 199 | BackgroundColor #F5F5F5 | ||
| 200 | BorderColor #5A5A5A | ||
| 201 | FontColor #262626 | ||
| 202 | } | ||
| 203 | skinparam stereotype { | ||
| 204 | CBackgroundColor #F5F5F5 | ||
| 205 | CBorderColor #5A5A5A | ||
| 206 | ABackgroundColor #F5F5F5 | ||
| 207 | ABorderColor #5A5A5A | ||
| 208 | IBackgroundColor #F5F5F5 | ||
| 209 | IBorderColor #5A5A5A | ||
| 210 | EBackgroundColor #F5F5F5 | ||
| 211 | EBorderColor #5A5A5A | ||
| 212 | NBackgroundColor #F5F5F5 | ||
| 213 | NBorderColor #5A5A5A | ||
| 214 | } | ||
| 215 | skinparam ArrowColor #0568AE | ||
| 216 | ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form | ||
| 217 | ' leaks its background onto every element in the diagram. | ||
| 218 | skinparam titleFontColor #0568AE | ||
| 219 | skinparam titleBorderColor #5A5A5A | ||
| 220 | ' Links otherwise take bluegray's white root colour, unreadable on a light fill. | ||
| 221 | <style> | ||
| 222 | root { | ||
| 223 | HyperLinkColor #0568AE | ||
| 224 | } | ||
| 225 | element { | ||
| 226 | HyperLinkColor #FFFFFF | ||
| 227 | } | ||
| 228 | actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface, | ||
| 229 | legend, node, package, rectangle { | ||
| 230 | HyperLinkColor #0568AE | ||
| 231 | } | ||
| 232 | </style> | ||
| 233 | ' ---- end XWiki accessible diagram palette ---- | ||
| 234 | skinparam componentStyle rectangle | ||
| 235 | left to right direction | ||
| 236 | |||
| 237 | actor "Reader" as USER | ||
| 238 | |||
| 239 | component "**Reverse proxy**\nApache HTTP Server or NginX\nterminates HTTPS, applies access control" as PROXY | ||
| 240 | component "**Servlet container**\nTomcat or Jetty\nreachable on the loopback interface only" as CONTAINER | ||
| 241 | component "**XWiki**\nreads the forwarded headers and\nbuilds URLs for the public address" as XWIKI | ||
| 242 | |||
| 243 | USER --> PROXY : HTTPS, port 443 | ||
| 244 | PROXY --> CONTAINER : HTTP, port 8080\nHost, X-Forwarded-For, X-Forwarded-Proto | ||
| 245 | CONTAINER --> XWIKI | ||
| 246 | XWIKI --> PROXY : pages and redirects carrying\nthe public HTTPS address | ||
| 247 | PROXY --> USER : answer, over HTTPS | ||
| 248 | @enduml | ||
| 249 | {{/plantuml}} | ||
| 250 | |||
| 251 | 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.installation.configuration-files.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. | ||
| 252 | |||
| 253 | Both Apache HTTP Server and NginX are used in front of XWiki; the choice usually follows whichever of them is already installed and administered. | ||
| 254 | |||
| 255 | * [[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##. | ||
| 256 | * [[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##. | ||
| 257 | * [[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. |