Wiki source code of HTTP Reverse Proxy for XWiki

Last modified by Eleni Cojocariu on 2026/11/17 17:14

Hide last authors
Eleni Cojocariu 4.2 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.
Eleni Cojocariu 1.1 2
Eleni Cojocariu 4.2 3 {{plantuml}}
4 @startuml
5 !theme bluegray
Eleni Cojocariu 6.3 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
Eleni Cojocariu 6.4 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
Eleni Cojocariu 6.3 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 ----
Eleni Cojocariu 4.2 234 skinparam componentStyle rectangle
235 left to right direction
Eleni Cojocariu 1.1 236
Eleni Cojocariu 4.2 237 actor "Reader" as USER
Eleni Cojocariu 1.4 238
Eleni Cojocariu 4.2 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
Eleni Cojocariu 6.5 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.
Eleni Cojocariu 4.2 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##.
Eleni Cojocariu 5.1 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.

Get Connected