summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames E. Blair <jeblair@redhat.com>2018-11-29 09:42:56 -0800
committerJames E. Blair <jeblair@redhat.com>2018-11-29 09:43:54 -0800
commit551f976e946bf649331f4d85f4ee7d9738cd6ca8 (patch)
treed05b5483908ddead6155b16d6366eef494aee824
parentfff02ace694de41da98240083588e02d4670d7e9 (diff)
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
Notes
Notes (review): Code-Review+2: Jens Harbott (frickler) <j.harbott@x-ion.de> Code-Review+2: Tobias Henkel <tobias.henkel@bmw.de> Workflow+1: Tobias Henkel <tobias.henkel@bmw.de> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Fri, 30 Nov 2018 07:56:06 +0000 Reviewed-on: https://review.openstack.org/620969 Project: openstack-infra/zuul Branch: refs/heads/master
-rw-r--r--doc/source/admin/installation.rst58
1 files changed, 33 insertions, 25 deletions
diff --git a/doc/source/admin/installation.rst b/doc/source/admin/installation.rst
index 781974e..1961ae6 100644
--- a/doc/source/admin/installation.rst
+++ b/doc/source/admin/installation.rst
@@ -169,11 +169,13 @@ repo and process any jobs defined therein.
169Web Deployment Options 169Web Deployment Options
170---------------------- 170----------------------
171 171
172The ``zuul-web`` service provides an web dashboard, a REST API and a websocket 172The ``zuul-web`` service provides a web dashboard, a REST API and a websocket
173log streaming service as a single holistic web application. For production use 173log streaming service as a single holistic web application. For production use
174it is recommended to run it behind a reverse proxy, such as Apache or Nginx. 174it is recommended to run it behind a reverse proxy, such as Apache or Nginx.
175 175
176More advanced users may desire to do one or more exciting things such as: 176The ``zuul-web`` service is entirely self-contained and can be run
177with minimal configuration, however, more advanced users may desire to
178do one or more of the following:
177 179
178White Label 180White Label
179 Serve the dashboard of an individual tenant at the root of its own domain. 181 Serve the dashboard of an individual tenant at the root of its own domain.
@@ -182,7 +184,7 @@ White Label
182 184
183Static Offload 185Static Offload
184 Shift the duties of serving static files, such as HTML, Javascript, CSS or 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
187Static External 189Static External
188 Serve the static files from a completely separate location that does not 190 Serve the static files from a completely separate location that does not
@@ -194,17 +196,17 @@ Sub-URL
194 https://softwarefactory-project.io/zuul/ is an example of a Zuul dashboard 196 https://softwarefactory-project.io/zuul/ is an example of a Zuul dashboard
195 that is being served from a Sub-URL. 197 that is being served from a Sub-URL.
196 198
197None of those make any sense for simple non-production oriented deployments, so 199Most deployments shouldn't need these, so the following discussion
198all discussion will assume that the ``zuul-web`` service is exposed via a 200will assume that the ``zuul-web`` service is exposed via a reverse
199Reverse Proxy. Where rewrite rule examples are given, they will be given 201proxy. Where rewrite rule examples are given, they will be given with
200with Apache syntax, but any other Reverse Proxy should work just fine. 202Apache syntax, but any other reverse proxy should work just fine.
201 203
202Basic Reverse Proxy 204Reverse Proxy
203~~~~~~~~~~~~~~~~~~~ 205~~~~~~~~~~~~~
204 206
205Using Apache as the Reverse Proxy requires the ``mod_proxy``, 207Using Apache as the reverse proxy requires the ``mod_proxy``,
206``mod_proxy_http`` and ``mod_proxy_wstunnel`` modules to be installed and 208``mod_proxy_http`` and ``mod_proxy_wstunnel`` modules to be installed
207enabled. Static Offload and White Label additionally require ``mod_rewrite``. 209and enabled.
208 210
209All of the cases require a rewrite rule for the websocket streaming, so the 211All of the cases require a rewrite rule for the websocket streaming, so the
210simplest reverse-proxy case is:: 212simplest reverse-proxy case is::
@@ -213,13 +215,16 @@ simplest reverse-proxy case is::
213 RewriteRule ^/api/tenant/(.*)/console-stream ws://localhost:9000/api/tenant/$1/console-stream [P] 215 RewriteRule ^/api/tenant/(.*)/console-stream ws://localhost:9000/api/tenant/$1/console-stream [P]
214 RewriteRule ^/(.*)$ http://localhost:9000/$1 [P] 216 RewriteRule ^/(.*)$ http://localhost:9000/$1 [P]
215 217
218This is the recommended configuration unless one of the following
219features is required.
216 220
217Static Offload 221Static Offload
218~~~~~~~~~~~~~~ 222~~~~~~~~~~~~~~
219 223
220To have the Reverse Proxy serve the static html/javascript assets instead of 224To have the reverse proxy serve the static html/javascript assets
221proxying them to the REST layer, register the location where you unpacked 225instead of proxying them to the REST layer, enable the ``mod_rewrite``
222the web application as the document root and add rewrite rules:: 226Apache module, register the location where you unpacked the web
227application as the document root and add rewrite rules::
223 228
224 <Directory /usr/share/zuul> 229 <Directory /usr/share/zuul>
225 Require all granted 230 Require all granted
@@ -244,7 +249,7 @@ the web application as the document root and add rewrite rules::
244Sub directory serving 249Sub directory serving
245~~~~~~~~~~~~~~~~~~~~~ 250~~~~~~~~~~~~~~~~~~~~~
246 251
247The web application needs to be rebuild to update the internal location of 252The web application needs to be rebuilt to update the internal location of
248the static files. Set the homepage setting in the package.json to an 253the static files. Set the homepage setting in the package.json to an
249absolute path or url. For example, to deploy the web interface through a 254absolute path or url. For example, to deploy the web interface through a
250'/zuul/' sub directory: 255'/zuul/' sub directory:
@@ -257,11 +262,12 @@ absolute path or url. For example, to deploy the web interface through a
257 262
258.. code-block:: bash 263.. code-block:: bash
259 264
260 sed -e 's#"homepage": "/"#"homepage": "/zuul/"#' -i package.json 265 sed -e 's#"homepage": "/"#"homepage": "/zuul/"#' -i package.json
261 yarn build 266 yarn build
262 267
263Then assuming the web application is unpacked in /usr/share/zuul, 268Then assuming the web application is unpacked in /usr/share/zuul,
264add the following rewrite rules:: 269enable the ``mod_rewrite`` Apache module and add the following rewrite
270rules::
265 271
266 <Directory /usr/share/zuul> 272 <Directory /usr/share/zuul>
267 Require all granted 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.. note:: 298.. note::
293 299
294 It's possible to do white-labelling without static offload, but it is more 300 It's possible to do white-labeling without static offload, but it
295 complex with no benefit. 301 is more complex with no benefit.
296 302
297Assuming the zuul tenant name is "example", the rewrite rules are:: 303Enable the ``mod_rewrite`` Apache module, and assuming the Zuul tenant
304name is ``example``, the rewrite rules are::
298 305
299 <Directory /usr/share/zuul> 306 <Directory /usr/share/zuul>
300 Require all granted 307 Require all granted
@@ -323,12 +330,13 @@ Static External
323 330
324.. note:: 331.. note::
325 332
326 Hosting zuul dashboard on an external static location that does not support 333 Hosting the Zuul dashboard on an external static location that does
327 dynamic url rewrite rules only works for white-labeled deployments. 334 not support dynamic url rewrite rules only works for white-labeled
335 deployments.
328 336
329In order to serve the zuul dashboard code from an external static location, 337In order to serve the zuul dashboard code from an external static location,
330``REACT_APP_ZUUl_API`` must be set at javascript build time: 338``REACT_APP_ZUUl_API`` must be set at javascript build time:
331 339
332.. code-block:: bash 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