Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@clintonium-119
clintonium-119 committed Mar 28, 2024
1 parent 77c9fd1 commit ec2a00e
Showing 1 changed file with 21 additions and 113 deletions.
134 changes: 21 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,119 +10,59 @@ This README is focused on just the details of getting blip running locally. For

### Table of contents

- [Before you start](#beforeyoustart)
- [Install](#install)
- [Running locally](#running-locally)
- ["Verifying" the e-mail of a new account locally](#getting-past-e-mail-verification-for-a-user-created-locally)
- [Creating a special account to bypass e-mail verification](#creating-a-user-without-email-verification)
- [Running against `dev`](#running-against-dev)
- [Config](#config)
- [Debugging](#debugging)
- [Running the tests](#running-the-tests)
- [Build and deployment](#build-and-deployment)
- [Using Storybook](#storybook)

* * * * *

## Before you start

If this is the first time you're looking at Tidepool locally start with the [tidepool-org/development](https://github.com/tidepool-org/development) repository to setup before continuing here.

## Install

Requirements:

- [Node.js](http://nodejs.org/ 'Node.js') version 6.x
- [npm](https://www.npmjs.com/ 'npm') version 4.x or higher
- [Node.js](http://nodejs.org/ 'Node.js') version 20.x
- [Yarn](https://yarnpkg.com/ 'Yarn') version 3.6.4 or higher

Clone this repo [from GitHub](https://github.com/tidepool-org/blip 'GitHub: blip'), then install the dependencies:
*Note for Mac users:* we suggest first uninstalling any old version of Yarn installed via Homebrew.

After cloning this repository to your local machine, first make sure that you have node `6.x` and npm `4.x` installed. If you have a different major version of node installed, consider using [nvm](https://github.com/creationix/nvm 'GitHub: Node Version Manager') to manage and switch between multiple node (& npm) installations. If you have npm `3.x` installed (as it is by default with node `6.x`), then you can update to the latest npm `4.x` with `npm install -g npm@4`.
Clone this repo [from GitHub](https://github.com/tidepool-org/blip 'GitHub: blip'), then install the dependencies:

It's not an absolute requirement, but it is preferable to have [Yarn](https://yarnpkg.com 'Yarn') installed, as it provides dependency management features above and beyond what npm provides. Just follow [Yarn's installation instructions](https://yarnpkg.com/en/docs/install 'Yarn installation instructions') (hint: for Mac users with Homebrew installed, it's just `brew install yarn`).
After cloning this repository to your local machine, first make sure that you have node `20.x` and yarn `3.6.4` or higher installed. If you have a different major version of node installed, consider using [nvm](https://github.com/creationix/nvm 'GitHub: Node Version Manager') to manage and switch between multiple node (& npm/yarn) installations.

Once your environment is setup with node `6.x` and npm `4.x` install the dependencies with Yarn:
Once your environment is setup with node `20.x` and yarn `3.6.4` or higher, install the dependencies with Yarn:

```bash
$ yarn install
```

Or with npm if you're choosing not to use Yarn:
## Running locally

```bash
$ npm install
```
While blip can be run locally using a local kubernetes deployment similar to our remote environments (see [tidepool-org/development](https://github.com/tidepool-org/development/)), it's recommended that you run this locally with the built-in webpack dev server, and point to one of our remote environments

## Running locally
To do this, copy `config/local.example.js` to `config/local.js` and update as needed:

If you're running the entire Tidepool platform locally with docker as per [tidepool-org/development](https://github.com/tidepool-org/development/#starting), you can start blip using your local platform with:
Uncomment any `linkedPackages` as desired to link them for local development.

```bash
$ docker-compose up -d
```
These will be resolved as aliases in the webpack config. Note that you will need to ensure that the packages are installed (via `yarn install`) in each respective folder

If you're running the entire Tidepool platform locally without docker, you can start blip using your local platform with:
It's recommended to use the `yarn startLocal` script to run the app, as it will automatically start the webpack development server for the `viz` repo when needed.

You may add as other modules to this list as well.

```bash
$ source config/local.sh
$ npm start
$ yarn startLocal
```

Open your web browser and navigate to `http://localhost:3000/`.

(See also: [recipe for running blip locally with hot module replacement](http://developer.tidepool.io/docs/front-end/recipes.html#a-running-the-platform-locally-with-runservers-but-blip-with-hot-module-replacement-hmr-via-webpack 'Tidepool developer portal: front end recipes').)

The `npm start` command runs the Webpack dev server which includes hot module reloading (HMR) capabilities. Essentially changes within React components should be updated "hot" in your browser *without* a page refresh. Sometimes this doesn't work, but in such cases the dev console will include a message from the Webpack dev server indicating that you need to do a full refresh to see your changes.

### Redux dev tools

Blip includes several Redux developer tools: the original time-travel dev tools UI, a console action logger, and a mutation tracker for catching mutations to the state tree (which should be immutable). The last of these in particular is a performance killer (though *none* of them could even be said to have a *negligible* effect on performance). By default when running for local development with `npm start` (which means `NODE_ENV` is `development`), the `DEV_TOOLS` flag will be `true`, and all of these dev tools will be active. Because they affect performance profoundly, this may not always be desirable. To turn *off* the dev tools in development, kill the Webpack dev server (i.e, the `npm start` process), run `export DEV_TOOLS=false`, then start up blip again with `npm start`.

**NB:** Due to differences in the `development` versus `production` builds of React itself (most notably PropTypes validation), performance of the app whenever `NODE_ENV` is `development` will *never* be as good as it is in the production build under a `NODE_ENV` of `production`. If you're concerned about the performance of a particular feature, the only way to test with good fidelity is with the production build, which you can do locally according to [these instructions below](#testing-the-production-build-locally).

### Getting past e-mail verification for a user created locally

When running locally with `runservers` or with the [docker-based setup](https://github.com/tidepool-org/development), no e-mail will be sent to a sign-up e-mail address, and so a workaround is needed to get past the e-mail verification step for a newly created local account being used for development. What you need to do is construct the login URL that is provided in a link in the verification e-mail *manually* by finding the correct key for the e-mail confirmation.

If you're developing locally, you can find the key by looking in the local `server.log` (located at the root level of where you've cloned all the Tidepool repositories).

If you're developing with the docker setup, you can find the key in the logs of the `hydrophone` container. It will look something like
```
2018/06/07 16:17:17 Sending email confirmation to foo@bar.com with key aSuzGcwq4kPRyb6pwQnTcSKVTt_V6CtL
```
[Kitematic](https://kitematic.com/) is an easy-to-use tool for inspecting the logs of your docker containers. You can find the link to it's installer in Docker's menu.

You can also find the key in your Mongo database. The steps for the latter are:

- start a Mongo shell in a fresh Terminal window with `mongo`
- switch to the `confirm` database with `use confirm`
- find the pending account with `db.confirmations.find({status: 'pending'});`
- copy the `_id` from the pending confirmation record with an `email` matching the account you've just created

After you've found the key, you can provide it as a `signupKey` parameter in the login URL: `http://localhost:3000/login?signupKey=<key>`

### Creating a user without e-mail verification

When running locally, there is also workaround so you don't have to verify the e-mail address of a new user: if you create a new user and add the localhost secret +skip to the e-mail address - e.g. `me+skip@something.org` - this will then allow you to login straightaway, skipping the e-mail verification step.

**NB: The UI is *not* guaranteed to display correctly for +skip-created users on all pages, and so 💣 *THIS WORKFLOW IS NOT CURRENTLY RECOMMENDED* 💣. For now, you must create a normal account (without +skip) if you want to work on the sign-up flow, although we have plans to fix the way the +skip workaround operates on the platform to address this.**

## Running against `dev`

By default—that is, if you don't `source` a different configuration, such as the `local.sh` configuration for local development with runservers referenced above—if you simply run `npm start` in this repository after installing the dependencies, blip will start up running against Tidepool's "dev" server environment.

## Config

Configuration values are set with environment variables (see `config/local.sh`).

You can set environment variables manually using `export VAR=value`, or use a bash script. For example:

```bash
$ source config/local.sh
```

Ask the project owners to provide you with config scripts for different environments, or you can create one of your own if you have a custom environment. It is recommended to put all config scripts in the `config/` directory, where they will be ignored by Git.

## Debugging

The app uses the [bows](http://latentflip.com/bows/) library to log debugging messages to the browser's console. It is disabled by default (which makes it production-friendly). To see the messages type `localStorage.debug = true` in the browser console and refresh the page. Create a logger for a particular app module by giving it a name, such as:
Expand All @@ -138,59 +78,27 @@ app.foo = {

## Running the tests

We use [Mocha](https://mochajs.org/) with [Chai](http://chaijs.com/) for our test framework inside [Karma](https://karma-runner.github.io/) as our test runner, as well as [Sinon.JS](http://sinonjs.org/) and [Sinon-Chai](https://github.com/domenic/sinon-chai) for spies and stubs. Our tests currently run on [PhantomJS](http://phantomjs.org/), a headless WebKit browser, or Chrome (locally only).
We use [Mocha](https://mochajs.org/) with [Chai](http://chaijs.com/) for our test framework inside [Karma](https://karma-runner.github.io/) as our test runner, as well as [Sinon.JS](http://sinonjs.org/) and [Sinon-Chai](https://github.com/domenic/sinon-chai) for spies and stubs. Our tests currently run on headless Chrome.

To run the unit tests, use:

```bash
$ npm test
```

To run the unit tests in Chrome, use:

```bash
$ npm run browser-tests
$ yarn test
```

To run the unit tests in watch mode, use:

```bash
$ npm run test-watch
```

## Build and deployment

The app is built as a static site in the `dist/` directory.

We use [Shio](https://github.com/tidepool-org/shio) to deploy, so we separate the build in two.

Shio's `build.sh` script will take care of building the app itself with:

```bash
$ npm run build-app
```

Shio's `start.sh` script then builds the config from environment variables as a separate file with:

```bash
$ source config/env.sh
$ npm run build-config
```

After that, the app is ready to be served using the static web server included in this repo:

```bash
$ npm run server
$ yarn run test-watch
```

### Testing the production build locally

You can also build everything at once locally to test the production build by simply running:

```bash
$ source config/local.sh
$ npm run build
$ npm run server
$ yarn build
$ yarn server
```


Expand All @@ -208,4 +116,4 @@ To run stylelint

```bash
$ npm run lint:css
```
```

0 comments on commit ec2a00e

Please sign in to comment.