Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thomaschampagne/elevate
A sport app to "Elevate" your training experience and goals! Track your fitness and progressions over time. Analyse deeper your activities. And more...
https://github.com/thomaschampagne/elevate
angular chrome cycling electron running strava swim webextension
Last synced: about 2 months ago
JSON representation
A sport app to "Elevate" your training experience and goals! Track your fitness and progressions over time. Analyse deeper your activities. And more...
- Host: GitHub
- URL: https://github.com/thomaschampagne/elevate
- Owner: thomaschampagne
- License: mpl-2.0
- Created: 2014-10-10T23:24:52.000Z (almost 10 years ago)
- Default Branch: develop
- Last Pushed: 2024-04-30T20:10:49.000Z (5 months ago)
- Last Synced: 2024-05-05T19:32:10.336Z (5 months ago)
- Topics: angular, chrome, cycling, electron, running, strava, swim, webextension
- Language: TypeScript
- Homepage: https://thomaschampagne.github.io/elevate-docs/
- Size: 52 MB
- Stars: 1,217
- Watchers: 43
- Forks: 177
- Open Issues: 129
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Elevate
- [Install](#install)
- [Desktop App](#desktop-app)
- [Download \& Install](#download--install)
- [Build from sources](#build-from-sources)
- [Web extension](#web-extension)
- [Download for _Chrome, Chromium, Edge (from 2020), Brave, Opera, Vivaldi, Yandex, ..._](#download-for-chrome-chromium-edge-from-2020-brave-opera-vivaldi-yandex-)
- [From the sources](#from-the-sources)
- [Development](#development)
- [Global solution structure](#global-solution-structure)
- [App-core project](#app-core-project)
- [Desktop project](#desktop-project)
- [Web-extension project](#web-extension-project)
- [Environments setup](#environments-setup)
- [Install requirements](#install-requirements)
- [Clone the git-flow based project](#clone-the-git-flow-based-project)
- [Desktop development environment](#desktop-development-environment)
- [Web extension development environment](#web-extension-development-environment)
- [Build with docker](#build-with-docker)
- [Desktop app](#desktop-app-1)
- [Web extension](#web-extension-1)
- [Appendix](#appendix)
- [Add a new desktop migration for a next release](#add-a-new-desktop-migration-for-a-next-release)
- [Sign application](#sign-application)
- [Self-sign with OpenSSL for windows build](#self-sign-with-openssl-for-windows-build)
- [Publish to github releases](#publish-to-github-releases)
- [Use custom browser for unit-testing (web-extension only)](#use-custom-browser-for-unit-testing-web-extension-only)
- [Desktop: Debug the calculated watts against real power](#desktop-debug-the-calculated-watts-against-real-power)
## Install
### Desktop App
#### Download & Install
- [For Windows](https://thomaschampagne.github.io/elevate-docs/Download-%26-Install/Windows/)
- [For macOS](https://thomaschampagne.github.io/elevate-docs/Download-%26-Install/macOS/)
- For Linux: not shipped yet
#### Build from sources
Go to chapter [Environment setup](#environments-setup).
### Web extension
#### Download for _Chrome, Chromium, Edge (from 2020), Brave, Opera, Vivaldi, Yandex, ..._
Go to [https://thomaschampagne.github.io/elevate/](https://thomaschampagne.github.io/elevate/)
#### From the sources
Go to chapter [Environment setup](#environments-setup).
## Development
This section covers the environment setup to develop and build both desktop app and web extension.
### Global solution structure
The solution is cut in 3 folders/projects: the `appcore`, the `desktop` & `webextension`
#### App-core project
Contains the _Elevate App_ shared and loaded by both `desktop` and `webextension`projects. Appcore contains core features like _fitness trend, year progressions, athlete settings..._
The `Appcore` main technology stack is:
- [Typescript](https://www.typescriptlang.org/) as programming language.
- [Angular](https://angular.io/) as frontend (build with [@angular/cli](https://cli.angular.io/)).
- [Angular Material](https://material.angular.io/) for material designed components.
- [Metrics Graphics](https://www.metricsgraphicsjs.org/), [Plotly](https://plotly.com/javascript/) & [D3](https://d3js.org/) for charting.
- [LokiJS](https://https://github.com/techfort/LokiJS) as in-memory NoSQL database persisted in IndexedDB.
- [Jest](https://jestjs.io/) as Javascript test runner (instead of "stock" karma one).
#### Desktop project
Holds the container behaviour to provide a cross-platform desktop app under _Windows, Linux & MacOS_. It contains desktop specific features like _connectors synchronization_ (to fetch athlete activities from external).
The `Desktop` main technology stack is:
- [Typescript](https://www.typescriptlang.org/) as programming language.
- [Jest](https://jestjs.io/) as Javascript test runner.
- [Electron](https://electronjs.org/) as cross-platform desktop container.
- [Electron-builder](https://www.electron.build/) to build, sign and publish installers per platform. Also handle app updates process (via `electron-updater`).
- [Rollup.js](https://rollupjs.org/guide/en/) to load & bundle modules.
- [Vue.js](https://vuejs.org/) for splash-screen update window.
#### Web-extension project
Contains the web extension behaviour that acts directly on _strava.com_ website. This includes _extended stats on activities & segments efforts, best splits, etc..._
### Environments setup
#### Install requirements
You will need to install [NodeJS](https://nodejs.org) (v15+) to build both desktop and chrome web extension.
#### Clone the [git-flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) based project
```bash
git clone https://github.com/thomaschampagne/elevate.git
```
or
```bash
git clone [email protected]:thomaschampagne/elevate.git
```
The new mono-repo including the desktop app and the web extension is on `develop-new` branch at the moment. So checkout/track this branch to build the desktop app:
```bash
cd ./elevate
git checkout --track origin/develop-new
```
Then install npm dependencies:
```bash
npm install
```
Run solution tests (`appcore` + `desktop` + `webextension`):
```bash
npm test
```
(_Should be executed with success for any pull request submission_).
#### Desktop development environment
All commands displayed in this section will be executed in `./desktop/` folder. So:
```bash
cd ./desktop/
```
- Run in development:
```bash
npm start
```
> This npm task will create a `./desktop/dist` output folder and re-compile both `appcore` and `desktop` projects on any code changes
To open the desktop app, open another terminal, then run:
```bash
npm run launch:dev:app
```
- Run unit tests:
```bash
npm test
```
- Generate production installers and publish them per platforms:
First switch to desktop directory with `cd desktop/`
- Build `Windows` `x64` `.exe`:
```bash
npm run build:publish:windows
```
- Build `Linux` `x64` `.deb`:
```bash
npm run build:publish:linux
```
- Build `MacOS` `x64` `.dmg` :
```bash
npm run build:publish:macos
```
> Output installers will be located in `./desktop/package/`
> The build targets are defined in `./desktop/package.json` (`build` key section). See [https://www.electron.build](https://www.electron.build) for more info.
- (Optional) To sign the production installers read the [how to sign appendix](#sign-application)
- (Optional) To publish the production installers on github read the [how to publish on github appendix](#publish-to-github-releases)
- Clean outputs:
```bash
npm run clean
```
#### Web extension development environment
_To develop the web extension, you need a Chrome based browser such as Chrome, Chromium, Edge (from 2020), Brave, Opera, Vivaldi, Yandex, ..._
All commands displayed in this section will be executed in `./webextension/` folder. So:
```bash
cd ./webextension/
```
- Run in development:
```bash
npm start
```
> This npm task will create a `./webextension/dist` output folder and re-compile both `appcore` and `webextension` projects on any code changes
- To load the web extension into your chrome based browser:
- Open new tab and type `chrome://extensions`, then enter.
- Tick `Developer Mode` checkbox.
- Click `Load Unpacked Extension` button, then choose `./webextension/dist` directory (this is where you have the `manifest.json` file)
- Make sure to disable other instances of elevate. You can re-enable them back from same tab.
- Open strava.com OR click on the Elevate icon in the browser toolbar.
- Run unit tests
```bash
npm test
```
- Production package
You can package the extension with the following command
```bash
npm run package
```
> Output release will be located in `./webextension/package/`
- Clean outputs:
```bash
npm run clean
```
### Build with docker
#### Desktop app
@TODO
#### Web extension
Create docker your image from `Dockerfile`
```bash
docker build . -t elevate-chrome-builder
```
Run a docker production build through a container. Replace `/path/to/your/directory/` with a folder on your host to fetch the packaged build when done.
```bash
docker run --rm --name elevate-chrome-build -v /path/to/your/directory/:/package elevate-chrome-builder
```
## Appendix
### Add a new desktop migration for a next release
Register your new migration in below file
```bash
./appcore/src/app/desktop/migration/desktop-registered-migrations.ts
```
**Tip:** to emulate a version upgrade, you may downgrade the `version` property inside `ipc.storage.json` file (user app data folder)
### Sign application
#### Self-sign with OpenSSL for windows build
- Create & edit a `code_sign.cnf` openssl config:
```bash
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
countryName = FR
stateOrProvinceName = Rhone Alpes
localityName = Grenoble
organizationName = Elevate
commonName = Elevate Sports App
emailAddress = [email protected]
[v3_req]
basicConstraints = CA:FALSE
keyUsage = critical,digitalSignature
extendedKeyUsage = critical,codeSigning
```
- Generate private key and certificate with a `passphrase`
```bash
openssl req -x509 -newkey rsa:4096 -sha256 -keyout code_sign.key -out code_sign.crt -days 1096 -config code_sign.cnf
```
- Create `.pxf` file from the private key and certificate previously generated. `.pxf` file will be used to sign app under windows.
```bash
openssl pkcs12 -export -name "elevate-sports-app" -out code_sign.pfx -inkey code_sign.key -in code_sign.crt
```
- Convert `.pxf` file to `base64`
```bash
base64 code_sign.pfx -w 0
```
- Create/edit `electron-builder.env` file under `./desktop/` folder, and add following keys:
```bash
CSC_LINK=
CSC_KEY_PASSWORD=
```
- Assign the `base64` previously generated to the key `CSC_LINK`
- Assign the `passphrase` previously used to the key `CSC_KEY_PASSWORD`
- Then run packaging for windows:
```bash
npm run package:windows
```
### Publish to github releases
- Generate a github personal access token at [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new)
- Tick `write:packages` scope. The `repo` and `read:packages` scopes should be automatically ticked too. Leave them ticked.
- Enter a `Note` for your token, then click `Generate token`. Keep this token safe. If lost you will have to re-generate one.
- Create/edit `electron-builder.env` file under `./desktop/` folder, and add following key:
```bash
GH_TOKEN=
```
- Assign the generated token to the key `GH_TOKEN`.
- Open `./desktop/package.json` file and go to the key `build.publish`.
- Edit the `owner` and `repo` variables to match with your target github repository.
_Note: To publish a new version on github, a github `draft release` has to exist on the remote target repo.
The github `draft release` value should match the `version` value of `./desktop/package.json` file.
New version must be compliant with [semver convention](https://semver.org/) and higher than previous version if exists.
You can use this [semver compare tool](https://semvercompare.azurewebsites.net/) that your new version is higher than your previous one._
- Open [https://github.com/your_owner/your_repo/releases](https://github.com/your_owner/your_repo/releases) and click `Draft a new release`.
- Enter the semver version to draft and click `Save draft`.
_Note: You may already pushed a git tag matching your version. If not, the git tag will be created on publish._
- Run packaging to publish installer:
```bash
npm run publish:win
```
or
```bash
npm run publish:mac
```
- Open [https://github.com/your_owner/your_repo/releases/edit/your_version](https://github.com/your_owner/your_repo/releases/edit/your_version): Some files should have been uploaded on the github draft release.
- You can update the uploaded files draft with a new packaging process. Once ready, click `Publish release`: users will receive the update.
### Use custom browser for unit-testing (web-extension only)
Create a `browsers.karma.conf.js` file in `webextension` folder.
To run unit test in a headless **chromium** instead of **chrome**, inject below javascript code:
```javascript
module.exports = {
browsers: [
"HeadlessChrome"
],
customLaunchers: {
HeadlessChrome: {
base: "Chromium",
flags: [
"--no-sandbox",
// See https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md
"--headless",
"--disable-gpu",
// Without a remote debugging port, Google Chrome exits immediately.
" --remote-debugging-port=9222"
]
}
}
};
```
### Desktop: Debug the calculated watts against real power
> This works in development build only
- Create a new local storage key named `DEBUG_EST_VS_REAL_WATTS` and set it to `true`
- Reload application and go to activities performed with a real power meter (cycling or running)