Doc update desktop readme (#2303)
* docs: ✏️ add troubleshooting info for node-gyp errors * docs: ✏️ clean up linting errors in desktop/README.md * docs: ✏️ include python install command
This commit is contained in:
Cameron Perera authored and 
GitHub committed
1 parent
5e3e61bc49
commit
5c8e93f5e9
1 file changed
+40
-31
+40
-31
@@ -12,17 +12,18 @@ The desktop client UI for Boundary.
|
||||
- [Yarn Commands](#yarn-commands)
|
||||
- [Running / Development](#running--development)
|
||||
- [Developing Using Non-Release Versions of Boundary](#developing-using-non-release-versions-of-boundary)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [Environment Variables (DEV)](#environment-variables-dev)
|
||||
- [Building for Production](#building-for-production)
|
||||
- [Environment Variables](#environment-variables-1)
|
||||
- [Environment Variables (PROD)](#environment-variables-prod)
|
||||
- [Running Tests](#running-tests)
|
||||
- [Running end to end Tests](#running-end-to-end-tests)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Blank screen and/or hang browser tab when running as web app](#blank-screen-andor-hang-browser-tab-when-running-as-web-app)
|
||||
- [Node-gyp build errors after package upgrades](#node-gyp-build-errors-after-package-upgrades)
|
||||
- [Deploying](#deploying)
|
||||
- [Debug desktop client](#debug-desktop-client)
|
||||
- [Debug `renderer` process](#debug-renderer-process)
|
||||
- [Debug `main` process ](#debug-main-process)
|
||||
- [Debug `main` process](#debug-main-process)
|
||||
- [Debug `binary`](#debug-binary)
|
||||
- [Further Reading / Useful Links](#further-reading--useful-links)
|
||||
|
||||
@@ -32,11 +33,11 @@ The desktop client UI for Boundary.
|
||||
|
||||
You will need the following things properly installed on your computer.
|
||||
|
||||
* [Git](https://git-scm.com/)
|
||||
* [Node.js](https://nodejs.org/)
|
||||
* [Yarn](https://yarnpkg.com/)
|
||||
* [Ember CLI](https://cli.emberjs.com/release/)
|
||||
* [Google Chrome](https://google.com/chrome/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Node.js](https://nodejs.org/)
|
||||
- [Yarn](https://yarnpkg.com/)
|
||||
- [Ember CLI](https://cli.emberjs.com/release/)
|
||||
- [Google Chrome](https://google.com/chrome/)
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -58,7 +59,7 @@ List of available project commands. `yarn run <command-name>`
|
||||
| lint:js | Lints `js` files. |
|
||||
| lint:js:fix | Runs the automatic linting fix for `js` files. |
|
||||
| lint:sass | Lints `scss` files. |
|
||||
| lint:electron | Runs a linter tool to identify misconfigurations and security anti-patterns in Electron. |
|
||||
| lint:electron | Runs a linter tool to identify misconfigurations and security anti-patterns in Electron. |
|
||||
| format | Runs all auto-formatters. |
|
||||
| format:hbs | Auto-formats `hbs` files using Prettier. |
|
||||
| format:js | Auto-formats `js` files using Prettier. |
|
||||
@@ -70,16 +71,17 @@ List of available project commands. `yarn run <command-name>`
|
||||
| test:ember | Runs ember tests in random order, with coverage reporting. |
|
||||
| doc:toc | Automatically generates a table of contents for this README file. |
|
||||
|
||||
|
||||
## Running / Development
|
||||
|
||||
To run as web app:
|
||||
* `yarn start`
|
||||
* Visit your app at [http://localhost:4201](http://localhost:4201).
|
||||
* Visit your tests at [http://localhost:4201/tests](http://localhost:4201/tests).
|
||||
|
||||
- `yarn start`
|
||||
- Visit your app at [http://localhost:4201](http://localhost:4201).
|
||||
- Visit your tests at [http://localhost:4201/tests](http://localhost:4201/tests).
|
||||
|
||||
To run as a desktop app:
|
||||
* `yarn start:desktop`
|
||||
|
||||
- `yarn start:desktop`
|
||||
|
||||
The Boundary CLI is downloaded and extracted to `electron-app/cli/` folder as part of
|
||||
build. CLI version is defined in `electron-app/config/cli.js`.
|
||||
@@ -91,10 +93,10 @@ above CLI download behavior - by manually placing the version of Boundary that
|
||||
you want to develop with in the `electron-app/cli/` directly (you may need to
|
||||
create the directory).
|
||||
|
||||
After doing this, run yarn with `BYPASS_CLI_SETUP=true`; example:
|
||||
After doing this, run yarn with `BYPASS_CLI_SETUP=true`; example:
|
||||
`BYPASS_CLI_SETUP=true yarn start:desktop`.
|
||||
|
||||
### Environment Variables
|
||||
### Environment Variables (DEV)
|
||||
|
||||
These environment variables may be used to customized the build.
|
||||
|
||||
@@ -112,7 +114,7 @@ These environment variables may be used to customized the build.
|
||||
### Building for Production
|
||||
|
||||
Before executing a build, be sure to set any environment variables necessary
|
||||
for your target [environment](#environment-variables). To build this UI for
|
||||
for your target [environment](#environment-variables-prod). To build this UI for
|
||||
production, run the following commands from this folder:
|
||||
|
||||
```bash
|
||||
@@ -134,25 +136,25 @@ Boundary](#developing-using-non-release-versions-of-boundary) for more details.
|
||||
|
||||
To build debian based linux artifacts on MacOS, additional [MacOS tools](https://www.electronforge.io/config/makers/deb) need to be installed before running the following commands from this folder.
|
||||
|
||||
```
|
||||
```bash
|
||||
yarn install
|
||||
yarn build:production # Build assets
|
||||
yarn build:desktop:debianOnMacOS # Build app
|
||||
```
|
||||
|
||||
#### Environment Variables
|
||||
#### Environment Variables (PROD)
|
||||
|
||||
These environment variables may be used to customized the build.
|
||||
|
||||
| Variable | Default Value | Description |
|
||||
| -------- | ------------- | ----------- |
|
||||
| `APP_NAME` | Application Name | The user-facing name of the application, appearing in titles, etc. |
|
||||
| `BOUNDARY_DESKTOP_SIGNING_IDENTITY` | | The name of the certificate to use when signing (e.g. Developer ID Application: * (*)). |
|
||||
| `BYPASS_CLI_SETUP` | Set to `true` to launch without bootstrapping the CLI (see above). |
|
||||
| `BOUNDARY_DESKTOP_SIGNING_IDENTITY` | | The name of the certificate to use when signing (e.g. Developer ID Application: \* (*)). |
|
||||
| `BYPASS_CLI_SETUP` | Set to `true` to launch without bootstrapping the CLI (see above). ||
|
||||
|
||||
### Running Tests
|
||||
|
||||
* `yarn test` runs full tests in random order with coverage
|
||||
- `yarn test` runs full tests in random order with coverage
|
||||
|
||||
Keep in mind that tests are executed in random order. This is intentional
|
||||
and helps to prevent hard-to-debug order dependencies among tests.
|
||||
@@ -172,23 +174,31 @@ route using `await a11yAudit();`.
|
||||
*Be aware this is a temporary process that can suffer changes and eventually will be automated.*
|
||||
|
||||
This process will explain how to run end to end test in your local environment. The process will assume next:
|
||||
|
||||
- You already run the Boundary UI [installation process](https://github.com/hashicorp/boundary-ui#installation).
|
||||
- You have Boundary installed, see [the installation guide](https://learn.hashicorp.com/tutorials/boundary/getting-started-install?in=boundary/getting-started).
|
||||
|
||||
Steps:
|
||||
|
||||
- Open a terminal and run `$ boundary dev`.
|
||||
- Open another terminal and navigate to `$ boundary-ui/ui/desktop` folder.
|
||||
- Run `$ yarn run e2e` and tests will start run.
|
||||
- You can check the screenshots the tests take: `desktop/tests/end2end/screenshots`.
|
||||
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Blank screen and/or hang browser tab when running as web app
|
||||
|
||||
We are aware of an issue of the desktop client not being able to start correctly when running as web app within development mode. This issue reproduces when the developer is enabling/disabling Mirage ([more info](#environment-variables) about environment variables).
|
||||
We are aware of an issue of the desktop client not being able to start correctly when running as web app within development mode. This issue reproduces when the developer is enabling/disabling Mirage ([more info](#environment-variables-dev) about environment variables).
|
||||
|
||||
The workaround to fix this issue is to reset/clear cookies and data (local storage and session storage).
|
||||
|
||||
#### Node-gyp build errors after package upgrades
|
||||
|
||||
This issue will likely pop up if you are using Python v3.12 and above as `python-setuptools` is no longer included by default.
|
||||
|
||||
If you are running into issues with running the desktop client after a node upgrade you may need to rebuild some tools needed for building the electron app. Be sure to remove `node_models/` for `ui/desktop/` and `ui/desktop/electron-app/` to make sure you have a clean slate. First thing you will need to check is if you have `python-setuptools` installed. It is needed for node-gyp to rebuild the native tools for electron. If you are on a mac and use Homebrew, you can run `brew install python-setuptools`. If you aren't using Homebrew you can run use tthe following command: `python3 -m pip install setuptools`. You should be able to run `yarn start:desktop` now. This will trigger the rebuild for electron but if you want to be safe you can run `./electron-app/node_modules/.bin/electron-rebuild` before trying to start up the desktop client.
|
||||
|
||||
### Deploying
|
||||
|
||||
TBD
|
||||
@@ -214,7 +224,7 @@ browserWindow.webContents.openDevTools()
|
||||
|
||||
`browserWindow` reference in our code, [here](https://github.com/hashicorp/boundary-ui/blob/main/ui/desktop/electron-app/src/index.js#L84).
|
||||
|
||||
### Debug `main` process
|
||||
### Debug `main` process
|
||||
|
||||
To start the electron app with the inspector adding a breakpoint before code starts:
|
||||
|
||||
@@ -237,11 +247,10 @@ The desktop client binary is the end artifact we deliver to customers. More info
|
||||
|
||||
We use [Debugtron](https://github.com/pd4d10/debugtron) to debug the production binary. Debugtron let's you inspect the Electron app as if you were in a dev environment. It also provides debug options for the node process running Electron.
|
||||
|
||||
|
||||
## Further Reading / Useful Links
|
||||
|
||||
* [ember.js](https://emberjs.com/)
|
||||
* [ember-cli](https://cli.emberjs.com/release/)
|
||||
* Development Browser Extensions
|
||||
* [ember inspector for chrome](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)
|
||||
* [ember inspector for firefox](https://addons.mozilla.org/en-US/firefox/addon/ember-inspector/)
|
||||
- [ember.js](https://emberjs.com/)
|
||||
- [ember-cli](https://cli.emberjs.com/release/)
|
||||
- Development Browser Extensions
|
||||
- [ember inspector for chrome](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)
|
||||
- [ember inspector for firefox](https://addons.mozilla.org/en-US/firefox/addon/ember-inspector/)
|
||||
Reference in new issue
Block a user