|
8 | 8 |
|
9 | 9 | Patch is one of the applications for console.redhat.com. It allows users to display and manage available patches for their registered systems. This repository containes source code for the frontend part of the application which uses the REST API available from [Patchman Engine](https://github.com/RedHatInsights/patchman-engine). |
10 | 10 |
|
11 | | -## Getting Started |
| 11 | +## First time setup |
| 12 | +1. Make sure you have [`Node.js`](https://nodejs.org/en/) version >= 18 installed |
| 13 | +2. Run [script to patch your `/etc/hosts`](https://github.com/RedHatInsights/insights-proxy/blob/master/scripts/patch-etc-hosts.sh) |
| 14 | +3. Make sure you are using [Red Hat proxy](https://hdn.corp.redhat.com/proxy.pac) if working against the stage environment. |
12 | 15 |
|
13 | | -The Patchman UI is a sub application under the Red Hat insights platform with [Insights chroming app as a wrapper](https://github.com/RedHatInsights/insights-chrome). |
14 | | - |
15 | | -There are 2 technologies used for integration with backend and deployment purposes: |
16 | | -1. [Insights Proxy](https://github.com/RedHatInsights/insights-proxy) |
17 | | -2. [Webpackproxy](https://github.com/RedHatInsights/frontend-components/tree/master/packages/config#useproxy) |
18 | | - |
19 | | -Note: the difference is insights proxy has to be reinitialised everytime you want to develop, while webpack proxy is auto initialized when you run the command ```npm run start:proxy:beta```. |
20 | | - |
21 | | -There is [a comprehensive quick start guide in the Storybook Documentation](https://github.com/RedHatInsights/insights-frontend-storybook/blob/master/src/docs/welcome/quickStart/DOC.md) to setting up an Insights environment complete with: |
22 | | - |
23 | | -- [Insights Frontend Starter App](https://github.com/RedHatInsights/frontend-starter-app) |
24 | | - |
25 | | -- [Insights Chroming](https://github.com/RedHatInsights/insights-chrome) |
26 | | - |
27 | | -- [Insights Proxy](https://github.com/RedHatInsights/insights-proxy) |
28 | | - |
29 | | -Note: You will need to set up the Insights environment if you want to develop with the starter app due to the consumption of the chroming service as well as setting up your global/app navigation through the API. |
30 | | - |
31 | | -## Run the app for the first time |
32 | | - |
33 | | -1. ```git clone git@github.com:RedHatInsights/patchman-ui.git``` |
34 | | - - clone the Patch UI into your machine |
35 | | - |
36 | | -2. ```npm install``` |
37 | | - |
38 | | -3. ```npm run start:proxy``` |
39 | | - - use this command if you want to develop Patch UI using insights proxy. The command starts webpack bundler and serves the files with webpack dev server |
40 | | - - While you run the command above, you will be prompted to choose an enviroment. |
41 | | - |
42 | | -Open browser with the URL generated by the webpack dev server your terminal |
43 | | - |
44 | | -### Testing |
45 | | - |
46 | | -- `npm run verify` will run linters and tests |
47 | | -- Travis is used to test the build for this code. |
48 | | - - You are always notified on failed builds |
49 | | - - You are only notified on successful builds if the build before it failed |
50 | | - - By default, both `push` events as well as `pull_request` events send notifications |
51 | | - - Travis is defaulted to notify #insights-bots |
52 | | - - `npm run test` will run only Jest tests |
53 | | - - `npm run test:update` is used to update the test snapshots |
| 16 | +## Running locally |
| 17 | +1. Make sure you are connected to the Red Hat VPN |
| 18 | +2. Install dependencies with `npm install` |
| 19 | +3. Run development server with `npm run start:proxy` and select desired environment (`stage-preview` is recommended) |
| 20 | +4. Local version of the app will be available at URL printed out to the console (https://stage.foo.redhat.com:1337/preview/insights/patch/ if you selected `stage-preview`) |
| 21 | + |
| 22 | +## Testing |
| 23 | +[Cypress](https://cypress.io/) and [Jest](https://jestjs.io/) are used as the testing frameworks |
| 24 | +- ```npm run test``` - run all Jest tests |
| 25 | +- ```npm run test:ct``` - open Cypress in the component testing mode. |
| 26 | +- ```npm run lint``` - run linter |
| 27 | +- ```npm run coverage``` - generate lect coverage information after running the tests |
54 | 28 |
|
55 | 29 | ## Deploying |
| 30 | +The app uses containerized builds which are configured in [`app-interface`](https://gitlab.cee.redhat.com/service/app-interface/-/blob/master/data/services/insights/patchman/deploy-clowder.yml). |
56 | 31 |
|
57 | | -- The Platform team is using Travis to deploy the application |
58 | | - - The Platform team will help you set up the Travis instance if this is the route you are wanting to take |
59 | | - |
60 | | -## Release process |
61 | | - |
62 | | -- [there is a comprehensive guidline on the release procedure](https://docs.engineering.redhat.com/pages/viewpage.action?spaceKey=SPM&title=Patch+UI+release+workflow) |
63 | | - |
64 | | -## Testing federated modules with another application |
| 32 | +| Environment | Available at | Deployed version |
| 33 | +| :----------------- | :--------------------------------------- | :---------- |
| 34 | +| stage preview | https://console.stage.redhat.com/preview | master branch |
| 35 | +| stage stable | https://console.stage.redhat.com | master branch |
| 36 | +| production preview | https://console.redhat.com/preview | up to the commit configured in `app-interface` |
| 37 | +| production stable | https://console.redhat.com | up to the commit configured in `app-interface` |
65 | 38 |
|
66 | | -If you want to test Patch with another application deployed locally, you can utilise `LOCAL_APPS` environment variable and deploy the needed application on separate ports. To learn more about the variable, see https://github.com/RedHatInsights/frontend-components/tree/master/packages/config#running-multiple-local-frontend-applications. |
67 | | - |
68 | | -### Example |
69 | | - |
70 | | -We'll take for example [insights-inventory-frontend](https://github.com/RedHatInsights/insights-inventory-frontend). |
71 | | - |
72 | | -Open new terminal, navigate to Inventory repository, and run it on a separate port without proxy: |
73 | | - |
74 | | -``` |
75 | | -npm run start -- --port=8003 |
76 | | -``` |
77 | | - |
78 | | -In a separate terminal, run Patch with proxy enabled and list Inventory: |
79 | | - |
80 | | -``` |
81 | | -LOCAL_APPS=inventory:8003~http npm run start:proxy |
82 | | -``` |
83 | | - |
84 | | -## Patternfly |
85 | | - |
86 | | -- This project imports Patternfly components: |
87 | | - - [Patternfly React](https://github.com/patternfly/patternfly-react) |
| 39 | +## Design System |
| 40 | +This project uses [Patternfly React](https://github.com/patternfly/patternfly-react). |
88 | 41 |
|
89 | 42 | ## Insights Components |
90 | | - |
91 | | -Insights Platform will deliver components and static assets through [npm](https://www.npmjs.com/package/@red-hat-insights/insights-frontend-components). ESI tags are used to import the [chroming](https://github.com/RedHatInsights/insights-chrome) which takes care of the header, sidebar, and footer. |
92 | | - |
93 | | -## Technologies |
94 | | - |
95 | | -### Webpack |
96 | | - |
97 | | -#### Webpack.config.js |
98 | | - |
99 | | -This file exports an object with the configuration for webpack and webpack dev server. |
100 | | - |
101 | | -```Javascript |
102 | | -{ |
103 | | - mode: https://webpack.js.org/concepts/mode/, |
104 | | - devtool: https://webpack.js.org/configuration/devtool/, |
105 | | - |
106 | | - // different bundle options. |
107 | | - // allows you to completely separate vendor code from app code and much more. |
108 | | - // https://webpack.js.org/plugins/split-chunks-plugin/ |
109 | | - optimization: { |
110 | | - chunks: https://webpack.js.org/plugins/split-chunks-plugin/#optimization-splitchunks-chunks-all, |
111 | | - runtimeChunk: https://webpack.js.org/plugins/split-chunks-plugin/#optimization-runtimechunk, |
112 | | - |
113 | | - // https://webpack.js.org/plugins/split-chunks-plugin/#configuring-cache-groups |
114 | | - cacheGroups: { |
115 | | - |
116 | | - // bundles all vendor code needed to run the entry file |
117 | | - common_initial: { |
118 | | - test: // file regex: /[\\/]node_modules[\\/]/, |
119 | | - name: // filename: 'common.initial', |
120 | | - chunks: // chunk type initial, async, all |
121 | | - } |
122 | | - } |
123 | | - }, |
124 | | - |
125 | | - // each property of entry maps to the name of an entry file |
126 | | - // https://webpack.js.org/concepts/entry-points/ |
127 | | - entry: { |
128 | | - |
129 | | - // example bunde names |
130 | | - bundle1: 'src/entry1.js', |
131 | | - bundle2: 'src/entry2.js' |
132 | | - }, |
133 | | - |
134 | | - // bundle output options. |
135 | | - output: { |
136 | | - filename: https://webpack.js.org/configuration/output/#output-filename, |
137 | | - path: https://webpack.js.org/configuration/output/#output-path, |
138 | | - publicPath: https://webpack.js.org/configuration/output/#output-publicpath, |
139 | | - chunkFilename: https://webpack.js.org/configuration/output/#output-chunkfilename |
140 | | - }, |
141 | | - module: { |
142 | | - rules: https://webpack.js.org/configuration/module/#module-rules |
143 | | - }, |
144 | | - |
145 | | - // An array of webpack plugins look at webpack.plugins.js |
146 | | - // https://webpack.js.org/plugins/ |
147 | | - plugins: [], |
148 | | - |
149 | | - // webpack dev serve options |
150 | | - // https://github.com/webpack/webpack-dev-server |
151 | | - devServer: {} |
152 | | -} |
153 | | -``` |
154 | | - |
155 | | -### React |
156 | | - |
157 | | -- High-Order Component |
158 | | - |
159 | | - - a [higher-order component](https://reactjs.org/docs/higher-order-components.html) is a function that takes a component and returns a new component |
160 | | - - Ex) [asyncComponent.js](https://github.com/RedHatInsights/insights-frontend-starter-app/src/Utils/asyncComponent.js) |
161 | | - |
162 | | -- [Smart/Presentational Components](https://medium.com/@thejasonfile/dumb-components-and-smart-components-e7b33a698d43) |
163 | | - - Smart components have access to the redux state |
164 | | - - Presentational components do not have access to the redux state |
165 | | - - Smart Components === insights-frontend/app/js/states |
166 | | - - Presentational Components === insights-frontend/app/js/components |
167 | | - |
168 | | -- [State and lifecycle within class components](https://reactjs.org/docs/state-and-lifecycle.html) |
169 | | - - article contains: |
170 | | - - Adding Lifecycle Methods to a Class |
171 | | - - Adding Local State to a Class |
172 | | - - State Updates May Be Asynchronous |
173 | | - - State Updates are Merged |
174 | | - |
175 | | -### Redux |
176 | | - |
177 | | -#### Store |
178 | | - |
179 | | -A [store](https://redux.js.org/basics/store) holds the whole [state tree](https://redux.js.org/glossary) of your application. |
180 | | -Redux doesn't have a Dispatcher or support many stores. Instead, there is just a single store with a single root reducing function. |
181 | | - |
182 | | -[Create Store](https://redux.js.org/api-reference/createstore): ```createStore(reducer, preloadedState, enhancer)``` |
183 | | - |
184 | | -- methods |
185 | | - - [getState()](https://redux.js.org/api-reference/store#dispatch) |
186 | | - - [dispatch(action)](https://redux.js.org/api-reference/store#dispatch) |
187 | | - - [subscribe(listener)](https://redux.js.org/api-reference/store#subscribe) |
188 | | - - [replaceReducer(nextReducer)](https://redux.js.org/api-reference/store#replaceReducer) |
189 | | - |
190 | | -#### Actions |
191 | | - |
192 | | -[Actions](https://redux.js.org/basics/actions) are payloads of information that send data from your application to your store. They are the only source of information for the store. You send them to the store using [store.dispatch()](https://redux.js.org/api-reference/store#dispatch). |
193 | | -Redux actions should only have two properties, type and payload, as a best practice. |
194 | | - |
195 | | -- Async Actions frameworks |
196 | | - |
197 | | - - [redux-promise-middleware](https://github.com/pburtchaell/redux-promise-middleware) |
198 | | - - Currently using this |
199 | | - - look at [/src/api/System/getSystems.js](https://github.com/RedHatInsights/turbo-octo-couscous/tree/master/src/api/System/getSystems.js) |
200 | | - - [redux-thunk](https://github.com/gaearon/redux-thunk) |
201 | | - - A function that wraps an expression to delay its evaluation |
202 | | - ```Javascript |
203 | | - // gotSystems(Error) are action creators |
204 | | - function getSystems() { |
205 | | - return function (dispatch) { |
206 | | - return fetchSystems().then( |
207 | | - systems => dispatch(gotSystems(systems)), |
208 | | - error => dispatch(gotSystemsError(error)) |
209 | | - ); |
210 | | - }; |
211 | | - } |
212 | | - ``` |
213 | | - - [redux-saga](https://github.com/yelouafi/redux-saga/) |
214 | | - - Uses [generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*) |
215 | | - - Could be a lot to learn initially. |
216 | | - - [redux-pack](https://github.com/lelandrichardson/redux-pack) |
217 | | - |
218 | | -#### Reducers |
219 | | - |
220 | | -[Reducers](https://redux.js.org/basics/reducers) specify how the application's state changes in response to actions sent to the store. |
221 | | - |
222 | | -Ex) [/src/api/System/getSystems.js](https://github.com/RedHatInsights/turbo-octo-couscous/tree/master/src/api/System/getSystems.js) |
223 | | - |
224 | | -### React-redux |
225 | | - |
226 | | -- [Provider](https://github.com/reactjs/react-redux/blob/master/docs/api.md#provider-store) |
227 | | - - Makes the Redux store available to the connect() |
228 | | -- [connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])](https://github.com/reactjs/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) |
229 | | - - Connects a React component to a Redux store |
230 | | - |
231 | | -### React-router-dom |
232 | | - |
233 | | -When setting up the routes, the page content is wrapped with a `.page__{pageName}` class, applied to the `#root` ID that is determined by the `rootClass` in the `Routes.js` which lets you easily reference the page in the styling. |
234 | | - |
235 | | -- [BrowserRouter](https://reacttraining.com/react-router/web/api/BrowserRouter) |
236 | | - - A `<Router>` that uses the HTML5 history API (pushState, replaceState and the popstate event) to keep your UI in sync with the URL |
237 | | -- [Route](https://reacttraining.com/react-router/web/api/Route) |
238 | | -- [Switch](https://reacttraining.com/react-router/web/api/Switch) |
239 | | - - Renders the first child `<Route>` or `<Redirect>` that matches the location. |
240 | | -- [Redirect](https://reacttraining.com/react-router/web/api/Redirect) |
241 | | - - navigate to a new location |
242 | | -- [withRouter](https://reacttraining.com/react-router/web/api/withRouter) |
243 | | - - passes updated match, location, and history props to the wrapped component whenever it renders |
244 | | - |
245 | | -## Running locally |
246 | | -Have [insights-proxy](https://github.com/RedHatInsights/insights-proxy) installed under PROXY_PATH |
247 | | - |
248 | | -```shell |
249 | | -SPANDX_CONFIG="./config/spandx.config.js" bash $PROXY_PATH/scripts/run.sh |
250 | | -``` |
251 | | - |
252 | | -### Running with inventory |
253 | | - |
254 | | -In order to test system detail in inventory application pull [inventory UI app](https://github.com/RedHatInsights/insights-inventory-frontend), install dependencies and run it |
255 | | - |
256 | | -```shell |
257 | | ->$ npm install |
258 | | ->$ npm start |
259 | | -``` |
260 | | - |
261 | | -With our spandx config, patch and inventory running you should be able to see changes in the system detail of inventory. |
262 | | - |
263 | | -### Testing - jest |
264 | | - |
265 | | -When you want to test your code with unit tests please use `jest` which is preconfigured in a way to colect codecoverage as well. If you want to see your coverage on server the travis config has been set in a way that it will send data to [codecov.io](https://codecov.io) the only thing you have to do is visit their website (register), enable your repository and add CODECOV_TOKEN to your travis web config (do not add it to .travis file, but trough [travis-ci.org](https://travis-ci.org/)) |
266 | | - |
267 | | -## Run SonarQube code analysis |
268 | | -~~~bash |
269 | | -export SONAR_HOST_URL=https://sonar-server |
270 | | -export SONAR_LOGIN=paste-your-generated-token |
271 | | -export SONAR_CERT_URL=https://secret-url-to/ca.crt # optional |
272 | | -podman-compose -f dev/sonar/docker-compose.yml up --build |
273 | | -~~~ |
| 43 | +This app imports components from [Insights Front-end Components library](https://github.com/RedHatInsights/frontend-components). ESI tags are used to import [Insights Chrome](https://github.com/RedHatInsights/insights-chrome) which takes care of the header, sidebar, and footer. |
0 commit comments