Skip to content

Latest commit

 

History

History
250 lines (173 loc) · 11.8 KB

README.md

File metadata and controls

250 lines (173 loc) · 11.8 KB
Raw

Desktop client UI

The desktop client UI for Boundary.

Table of Contents generated with DocToc

Prerequisites

You will need the following things properly installed on your computer.

Installation

See boundary-ui README for installation instructions.

Yarn Commands

List of available project commands. yarn run <command-name>

Command Description
build Builds the UI for production.
build:development Builds the UI in development mode.
build:desktop:debianOnMacOS Builds debian based linux artifacts on MacOS.
lint Runs all lint commands.
lint:fix Runs all automatic linting fixes.
lint:hbs Lints hbs template files.
lint:hbs:fix Runs the automatic linting fix for hbs template files.
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.
format Runs all auto-formatters.
format:hbs Auto-formats hbs files using Prettier.
format:js Auto-formats js files using Prettier.
format:sass Auto-formats scss files using Prettier.
start Runs the dummy app local server as web app.
start:desktop Runs the dummy app as an electron app.
clean:coverage Cleans coverage reporting directory.
test Runs all tests in random order, with coverage reporting.
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:

To run as a desktop app:

  • yarn start:desktop

The Boundary CLI is NOT downloaded by default, to download and extract the CLI to electron-app/cli folder as part of the build, you need to set the environment variable SETUP_CLI to true. Example: SETUP_CLI=true yarn start:desktop. The CLI version is defined in electron-app/config/cli/VERSION.

Developing Using Non-Release Versions of Boundary

To develop using a non-release version of Boundary, download the Boundary CLI version you want to use and extract it to the electron-app/cli folder. You may need to create the directory or clean it up beforehand.

Environment Variables (DEV)

These environment variables may be used to customized the build.

Variable Description
DEBUG_APP_UPDATER Enable to debug app updater feature. Must be enabled for all APP_UPDATER_* variables to be used.
APP_UPDATER_CURRENT_VERSION Version of client.
APP_UPDATER_LATEST_VERSION_TAG Next version for comparison with current version.
APP_UPDATER_LATEST_VERSION_LOCATION Location of app release to use for updating client. Can be a filepath or url.
SETUP_CLI Enable download and extraction of CLI.
BYPASS_APP_UPDATER Disable app updater feature. For development use only.
DISABLE_WINDOW_CHROME Disable window chrome. For internal use only.
ENABLE_MIRAGE Enable (true) or disable (false) mirage. Default value is true.

Building for Production

Before executing a build, be sure to set any environment variables necessary for your target environment and you have full permissions in the environment you want to build in. To build this UI for production, run the following commands from this folder:

yarn install
yarn build

BOUNDARY_DESKTOP_SIGNING_IDENTITY environment variable must be provided to codesign MacOS artifacts in production.

The static production assets are saved into the dist/ folder. The Boundary CLI is downloaded and extracted to electron-app/cli/ folder as part of packaging. CLI version is defined in electron-app/config/cli.js.

Similar to running in development, you can also use BYPASS_CLI_SETUP=true to bypass the download of the CLI, which can be useful for pre-release testing. See Developing Using Non-Release Versions of Boundary for more details.

To build debian based linux artifacts on MacOS, additional MacOS tools need to be installed before running the following commands from this folder.

yarn install
yarn build:production # Build assets
yarn build:desktop:debianOnMacOS # Build app

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: * (*)).
SETUP_CLI Enable download and extraction of CLI.

Running Tests

  • 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.

Please also note that we report test coverage. We strive for "the right amount of testing". Use test coverage as a guide to help you identify untested high-value code.

We rely on ember-a11y-testing to validate accessibility in acceptance tests. If you write acceptance tests, please ensure at least one validation per route using await a11yAudit();.

Running end to end Tests

The end-to-end test suite is supported for Mac, x64 and arm64 (M1) chips.

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:

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 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

Debug desktop client

There are two processes we can debug, renderer process and main process.

When I do need to debug the main process?

To debug code that is just executed in the main process, i.e to debug the ipcMain handler.

Debug renderer process

To debug the renderer process, once the electron app is running, open the Chrome DevTools.

You can open the Chrome DevTools programmatically by calling the API on the webContents instance:

const browserWindow = new BrowserWindow(browserWindowOptions);
browserWindow.webContents.openDevTools()

browserWindow reference in our code, here.

Debug main process

To start the electron app with the inspector adding a breakpoint before code starts:

$ yarn start:desktop --- --inspect-brk.

To avoid the breakpoint:

$ yarn start:desktop --- --inspect.

You can use any of these clients, but we will use the chrome inspector client. Open chrome and on the url bar: $ chrome://inspect and click inspect on the electron instance.

If you start the inspector with the -brk (breakpoint) code will not execute until you allow execution to continue (clicking the play button on the inspector).

More information on debugging the main process. More information on Node debugging guide.

Debug binary

The desktop client binary is the end artifact we deliver to customers. More information on how to build the binary in Building for Production.

We use 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