Monty Taylor | 4a781a7 | 2017-07-25 07:28:04 -0400 | [diff] [blame] | 1 | Zuul Web Javascript |
| 2 | =================== |
| 3 | |
| 4 | zuul-web has an html, css and javascript component that is managed |
| 5 | using Javascript toolchains. It is intended to be served by zuul-web |
| 6 | directly from zuul/web/static in the simple case, or to be published to |
| 7 | an alternate static web location, such as an Apache server. |
| 8 | |
| 9 | The web applications are managed by `yarn`_ and `webpack`_ which in turn both |
| 10 | assume a functioning and recent `nodejs`_ installation. |
| 11 | |
| 12 | For the impatient who don't want deal with javascript toolchains |
| 13 | ---------------------------------------------------------------- |
| 14 | |
| 15 | tl;dr - You have to build stuff with javascript tools. |
| 16 | |
| 17 | The best thing would be to get familiar with the tools, there are a lot of |
| 18 | good features available. But, if you don't want to know anything about the |
| 19 | Javascript toolchains a few helpers have been provided. |
| 20 | |
| 21 | If you have npm and docker installed and don't want to install newer nodejs |
| 22 | or a bunch of javascript libraries, you can run: |
| 23 | |
| 24 | .. code-block:: bash |
| 25 | |
| 26 | npm run build:docker |
| 27 | |
| 28 | If you have docker but do not have npm or nodejs installed, you can build |
| 29 | the web app with: |
| 30 | |
| 31 | .. code-block:: bash |
| 32 | |
| 33 | docker run -it --rm -v $(PWD):/usr/src/app -w /usr/src/app node:alpine \ |
| 34 | npm run build:dist-with-depends |
| 35 | |
| 36 | Both do the same thing. Both versions will result in the built files being |
| 37 | put into ``zuul/web/static``. |
| 38 | |
| 39 | .. note:: Because the user inside of the Docker container is root, the files |
| 40 | that it emits into zuul/web/static will be owned by root. |
| 41 | |
| 42 | yarn dependency management |
| 43 | -------------------------- |
| 44 | |
| 45 | `yarn`_ manages the javascript dependencies. That means the first step is |
| 46 | getting `yarn`_ installed. |
| 47 | |
| 48 | .. code-block:: bash |
| 49 | |
| 50 | tools/install-js-tools.sh |
| 51 | |
| 52 | The ``tools/install-js-tools.sh`` script will add apt or yum repositories and |
| 53 | install `nodejs`_ and `yarn`_ from them. For RPM-based distros it needs to know |
| 54 | which repo description file to download, so it calls out to |
| 55 | ``tools/install-js-repos-rpm.sh``. |
| 56 | |
| 57 | Once yarn is installed, getting dependencies installed is: |
| 58 | |
| 59 | .. code-block:: bash |
| 60 | |
| 61 | yarn install |
| 62 | |
| 63 | The ``yarn.lock`` file contains all of the specific versions that were |
| 64 | installed before. Since this is an application it has been added to the repo. |
| 65 | |
| 66 | To add new dependencies: |
| 67 | |
| 68 | .. code-block:: bash |
| 69 | |
| 70 | yarn add awesome-package |
| 71 | |
| 72 | To remove dependencies: |
| 73 | |
| 74 | .. code-block:: bash |
| 75 | |
| 76 | yarn remove terrible-package |
| 77 | |
| 78 | Adding or removing packages will add the logical dependency to ``package.json`` |
| 79 | and will record the version of the package and any of its dependencies that |
| 80 | were installed into ``yarn.lock`` so that other users can simply run |
| 81 | ``yarn install`` and get the same environment. |
| 82 | |
| 83 | To update a dependency: |
| 84 | |
| 85 | .. code-block:: bash |
| 86 | |
| 87 | yarn add awesome-package |
| 88 | |
| 89 | Dependencies are installed into the ``node_modules`` directory. Deleting that |
| 90 | directory and re-running ``yarn install`` should always be safe. |
| 91 | |
| 92 | webpack asset management |
| 93 | ------------------------ |
| 94 | |
| 95 | `webpack`_ takes care of bundling web assets for deployment, including tasks |
| 96 | such as minifying and transpiling for older browsers. It takes a |
| 97 | javascript-first approach, and generates a html file that includes the |
| 98 | appropriate javascript and CSS to get going. |
| 99 | |
| 100 | We need to modify the html generated for each of our pages, so there are |
| 101 | templates in ``web/templates``. |
| 102 | |
| 103 | The main `webpack`_ config file is ``webpack.config.js``. In the Zuul tree that |
| 104 | file is a stub file that includes either a dev or a prod environment from |
| 105 | ``web/config/webpack.dev.js`` or ``web/config/webpack.prod.js``. Most of the |
| 106 | important bits are in ``web/config/webpack.common.js``. |
| 107 | |
| 108 | Development |
| 109 | ----------- |
| 110 | |
| 111 | Building the code can be done with: |
| 112 | |
| 113 | .. code-block:: bash |
| 114 | |
| 115 | npm run build |
| 116 | |
| 117 | zuul-web has a ``static`` route defined which serves files from |
| 118 | ``zuul/web/static``. ``npm run build`` will put the build output files |
| 119 | into the ``zuul/web/static`` directory so that zuul-web can serve them. |
| 120 | |
| 121 | There is a also a development-oriented version of that same command: |
| 122 | |
| 123 | .. code-block:: bash |
| 124 | |
| 125 | npm run build:dev |
| 126 | |
| 127 | which will build for the ``dev`` environment. This causes some sample data |
| 128 | to be bundled and included. |
| 129 | |
| 130 | Webpack includes a development server that handles things like reloading and |
| 131 | hot-updating of code. The following: |
| 132 | |
| 133 | .. code-block:: bash |
| 134 | |
| 135 | npm run start |
| 136 | |
| 137 | will build the code and launch the dev server on `localhost:8080`. It will |
| 138 | additionally watch for changes to the files and re-compile/refresh as needed. |
| 139 | Arbitrary command line options will be passed through after a ``--`` such as: |
| 140 | |
| 141 | .. code-block:: bash |
| 142 | |
| 143 | npm run start -- --open-file='static/status.html' |
| 144 | |
| 145 | That's kind of annoying though, so additional targets exist for common tasks: |
| 146 | |
| 147 | Run status against `basic` built-in demo data. |
| 148 | |
| 149 | .. code-block:: bash |
| 150 | |
| 151 | npm run start:status:basic |
| 152 | |
| 153 | Run status against `openstack` built-in demo data |
| 154 | |
| 155 | .. code-block:: bash |
| 156 | |
| 157 | npm run start:status:openstack |
| 158 | |
| 159 | Run status against `tree` built-in demo data. |
| 160 | |
| 161 | .. code-block:: bash |
| 162 | |
| 163 | npm run start:status:tree |
| 164 | |
| 165 | Run status against live data from OpenStack's Zuul. |
| 166 | |
| 167 | .. code-block:: bash |
| 168 | |
| 169 | npm run start:status |
| 170 | |
| 171 | Run builds against live data from OpenStack's Zuul. |
| 172 | |
| 173 | .. code-block:: bash |
| 174 | |
| 175 | npm run start:builds |
| 176 | |
| 177 | Run jobs against live data from OpenStack's Zuul. |
| 178 | |
| 179 | .. code-block:: bash |
| 180 | |
| 181 | npm run start:jobs |
| 182 | |
| 183 | Run console streamer. |
| 184 | |
| 185 | .. note:: There is not currently a good way to pass build_id paramter. |
| 186 | |
| 187 | .. code-block:: bash |
| 188 | |
| 189 | npm run start:stream |
| 190 | |
| 191 | Additional run commands can be added in `package.json` in the ``scripts`` |
| 192 | section. |
| 193 | |
| 194 | Deploying |
| 195 | --------- |
| 196 | |
| 197 | The web application is a set of static files and is designed to be served |
| 198 | by zuul-web from its ``static`` route. In order to make sure this works |
| 199 | properly, the javascript build needs to be performed so that the javascript |
| 200 | files are in the ``zuul/web/static`` directory. Because the javascript |
| 201 | build outputs into the ``zuul/web/static`` directory, as long as |
| 202 | ``npm run build`` has been done before ``pip install .`` or |
| 203 | ``python setup.py sdist``, all the files will be where they need to be. |
| 204 | |
| 205 | Debugging minified code |
| 206 | ----------------------- |
| 207 | |
| 208 | Both the ``dev`` and ``prod`` ennvironments use the same `devtool`_ |
| 209 | called ``source-map`` which makes debugging errors easier by including mapping |
| 210 | information from the minified and bundled resources to their approriate |
| 211 | non-minified source code locations. Javascript errors in the browser as seen |
| 212 | in the developer console can be clicked on and the appropriate actual source |
| 213 | code location will be shown. |
| 214 | |
| 215 | ``source-map`` is considered an appropriate `devtool`_ for production, but has |
| 216 | the downside that it is slower to update. However, since it includes the most |
| 217 | complete mapping information and doesn't impact execution performance, so in |
| 218 | our case we use it for both. |
| 219 | |
| 220 | .. _yarn: https://yarnpkg.com/en/ |
| 221 | .. _nodejs: https://nodejs.org/ |
| 222 | .. _webpack: https://webpack.js.org/ |
| 223 | .. _devtool: https://webpack.js.org/configuration/devtool/#devtool |