Browse Source

More strongly recommend the simple reverse proxy deployment

Static offloading is fragile and more subject to change than
the simple reverse proxy, so emphasize the simple case in
documentation.

Change-Id: I19aaba595c4f1a392bad2be2969a9ed600c30d2f
tags/3.4.0
James E. Blair 5 months ago
parent
commit
551f976e94
1 changed files with 33 additions and 25 deletions
  1. 33
    25
      doc/source/admin/installation.rst

+ 33
- 25
doc/source/admin/installation.rst View File

@@ -169,11 +169,13 @@ repo and process any jobs defined therein.
169 169
 Web Deployment Options
170 170
 ----------------------
171 171
 
172
-The ``zuul-web`` service provides an web dashboard, a REST API and a websocket
172
+The ``zuul-web`` service provides a web dashboard, a REST API and a websocket
173 173
 log streaming service as a single holistic web application. For production use
174 174
 it is recommended to run it behind a reverse proxy, such as Apache or Nginx.
175 175
 
176
-More advanced users may desire to do one or more exciting things such as:
176
+The ``zuul-web`` service is entirely self-contained and can be run
177
+with minimal configuration, however, more advanced users may desire to
178
+do one or more of the following:
177 179
 
178 180
 White Label
179 181
   Serve the dashboard of an individual tenant at the root of its own domain.
@@ -182,7 +184,7 @@ White Label
182 184
 
183 185
 Static Offload
184 186
   Shift the duties of serving static files, such as HTML, Javascript, CSS or
185
-  images to the Reverse Proxy server.
187
+  images to the reverse proxy server.
186 188
 
187 189
 Static External
188 190
   Serve the static files from a completely separate location that does not
@@ -194,17 +196,17 @@ Sub-URL
194 196
   https://softwarefactory-project.io/zuul/ is an example of a Zuul dashboard
195 197
   that is being served from a Sub-URL.
196 198
 
197
-None of those make any sense for simple non-production oriented deployments, so
198
-all discussion will assume that the ``zuul-web`` service is exposed via a
199
-Reverse Proxy. Where rewrite rule examples are given, they will be given
200
-with Apache syntax, but any other Reverse Proxy should work just fine.
199
+Most deployments shouldn't need these, so the following discussion
200
+will assume that the ``zuul-web`` service is exposed via a reverse
201
+proxy. Where rewrite rule examples are given, they will be given with
202
+Apache syntax, but any other reverse proxy should work just fine.
201 203
 
202
-Basic Reverse Proxy
203
-~~~~~~~~~~~~~~~~~~~
204
+Reverse Proxy
205
+~~~~~~~~~~~~~
204 206
 
205
-Using Apache as the Reverse Proxy requires the ``mod_proxy``,
206
-``mod_proxy_http`` and ``mod_proxy_wstunnel`` modules to be installed and
207
-enabled. Static Offload and White Label additionally require ``mod_rewrite``.
207
+Using Apache as the reverse proxy requires the ``mod_proxy``,
208
+``mod_proxy_http`` and ``mod_proxy_wstunnel`` modules to be installed
209
+and enabled.
208 210
 
209 211
 All of the cases require a rewrite rule for the websocket streaming, so the
210 212
 simplest reverse-proxy case is::
@@ -213,13 +215,16 @@ simplest reverse-proxy case is::
213 215
   RewriteRule ^/api/tenant/(.*)/console-stream ws://localhost:9000/api/tenant/$1/console-stream [P]
214 216
   RewriteRule ^/(.*)$ http://localhost:9000/$1 [P]
215 217
 
218
+This is the recommended configuration unless one of the following
219
+features is required.
216 220
 
217 221
 Static Offload
218 222
 ~~~~~~~~~~~~~~
219 223
 
220
-To have the Reverse Proxy serve the static html/javascript assets instead of
221
-proxying them to the REST layer, register the location where you unpacked
222
-the web application as the document root and add rewrite rules::
224
+To have the reverse proxy serve the static html/javascript assets
225
+instead of proxying them to the REST layer, enable the ``mod_rewrite``
226
+Apache module, register the location where you unpacked the web
227
+application as the document root and add rewrite rules::
223 228
 
224 229
   <Directory /usr/share/zuul>
225 230
     Require all granted
@@ -244,7 +249,7 @@ the web application as the document root and add rewrite rules::
244 249
 Sub directory serving
245 250
 ~~~~~~~~~~~~~~~~~~~~~
246 251
 
247
-The web application needs to be rebuild to update the internal location of
252
+The web application needs to be rebuilt to update the internal location of
248 253
 the static files. Set the homepage setting in the package.json to an
249 254
 absolute path or url. For example, to deploy the web interface through a
250 255
 '/zuul/' sub directory:
@@ -257,11 +262,12 @@ absolute path or url. For example, to deploy the web interface through a
257 262
 
258 263
 .. code-block:: bash
259 264
 
260
-  sed -e 's#"homepage": "/"#"homepage": "/zuul/"#' -i package.json
261
-  yarn build
265
+   sed -e 's#"homepage": "/"#"homepage": "/zuul/"#' -i package.json
266
+   yarn build
262 267
 
263 268
 Then assuming the web application is unpacked in /usr/share/zuul,
264
-add the following rewrite rules::
269
+enable the ``mod_rewrite`` Apache module and add the following rewrite
270
+rules::
265 271
 
266 272
   <Directory /usr/share/zuul>
267 273
     Require all granted
@@ -291,10 +297,11 @@ rule to ensure connection webhooks don't try to get put into the tenant scope.
291 297
 
292 298
 .. note::
293 299
 
294
-  It's possible to do white-labelling without static offload, but it is more
295
-  complex with no benefit.
300
+   It's possible to do white-labeling without static offload, but it
301
+   is more complex with no benefit.
296 302
 
297
-Assuming the zuul tenant name is "example", the rewrite rules are::
303
+Enable the ``mod_rewrite`` Apache module, and assuming the Zuul tenant
304
+name is ``example``, the rewrite rules are::
298 305
 
299 306
   <Directory /usr/share/zuul>
300 307
     Require all granted
@@ -323,12 +330,13 @@ Static External
323 330
 
324 331
 .. note::
325 332
 
326
-  Hosting zuul dashboard on an external static location that does not support
327
-  dynamic url rewrite rules only works for white-labeled deployments.
333
+   Hosting the Zuul dashboard on an external static location that does
334
+   not support dynamic url rewrite rules only works for white-labeled
335
+   deployments.
328 336
 
329 337
 In order to serve the zuul dashboard code from an external static location,
330 338
 ``REACT_APP_ZUUl_API`` must be set at javascript build time:
331 339
 
332 340
 .. code-block:: bash
333 341
 
334
-  REACT_APP_ZUUL_API='http://zuul-web.example.com' yarn build
342
+   REACT_APP_ZUUL_API='http://zuul-web.example.com' yarn build

Loading…
Cancel
Save