open-source-mirrors
/
scrutiny
mirror of https://github.com/AnalogJ/scrutiny
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

updating CONTRIBUTING.md guide.

Browse Source
pull/263/head
Jason Kulatunga 2 years ago
parent e95b44c690
commit 12e624a496
1 changed files with 119 additions and 81 deletions
Show Stats Download Patch File Download Diff File

200
CONTRIBUTING.md
Unescape View File

@ -1,75 +1,109 @@
# Contributing # Contributing
There are multiple ways to develop on the scrutiny codebase locally. The two most popular are: The Scrutiny repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing source code for:
- Docker Development Container - only requires docker - Scrutiny Backend Server (API)
- Run Components Locally - requires smartmontools, golang & nodejs installed locally - Scrutiny Frontend Angular SPA
- S.M.A.R.T Collector
## Docker Development
``` Depending on the functionality you are adding, you may need to setup a development environment for 1 or more projects.
docker build -f docker/Dockerfile . -t chcr.io/analogj/scrutiny:master-omnibus
docker run -it --rm -p 8080:8080 \ # Modifying the Scrutiny Backend Server (API)
-v /run/udev:/run/udev:ro \
--cap-add SYS_RAWIO \ 1. install the [Go runtime](https://go.dev/doc/install) (v1.17+)
--device=/dev/sda \ 2. download the `scrutiny-web-frontend.tar.gz` for the [latest release](https://github.com/AnalogJ/scrutiny/releases/latest). Extract to a folder named `dist`
--device=/dev/sdb \ 3. create a `scrutiny.yaml` config file
ghcr.io/analogj/scrutiny:master-omnibus ```yaml
/opt/scrutiny/bin/scrutiny-collector-metrics run # config file for local development. store as scrutiny.yaml
``` version: 1
web:
## Local Development listen:
port: 8080
### Frontend host: 0.0.0.0
The frontend is written in Angular. database:
If you're working on the frontend and can use mocked data rather than a real backend, you can use # can also set absolute path here
``` location: ./scrutiny.db
cd webapp/frontend src:
npm install frontend:
ng serve --deploy-url="/web/" --base-href="/web/" path: ./dist
``` influxdb:
retention_policy: false
However, if you need to also run the backend, and use real data, you'll need to run the following command:
``` log:
cd webapp/frontend && ng build --watch --output-path=../../dist --prod file: 'web.log' #absolute or relative paths allowed, eg. web.log
``` level: DEBUG
> Note: if you do not add `--prod` flag, app will display mocked data for api calls. ```
4. start a InfluxDB docker container.
### Backend ```bash
docker run -p 8086:8086 --rm influxdb:2.2
If you're using the `ng build` command above to generate your frontend, you'll need to create a custom config file and ```
override the `web.src.frontend.path` value. 5. start the scrutiny web server
```bash
``` go mod vendor
# config file for local development. store as scrutiny.yaml go run webapp/backend/cmd/scrutiny/scrutiny.go start --config ./scrutiny.yaml
version: 1 ```
6. open your browser to [http://localhost:8080/web](http://localhost:8080/web)
web:
listen: # Modifying the Scrutiny Frontend Angular SPA
port: 8080
host: 0.0.0.0 The frontend is written in Angular. If you're working on the frontend and can use mocked data rather than a real backend, you can follow the instructions below:
database:
# can also set absolute path here 1. install [NodeJS](https://nodejs.org/en/download/)
location: ./scrutiny.db 2. start the Angular Frontend Application
src: ```bash
frontend: cd webapp/frontend
path: ./dist npm install
influxdb: ng serve --deploy-url="/web/" --base-href="/web/" --port 4200
retention_policy: false ```
3. open your browser and visit [http://localhost:4200/web](http://localhost:4200/web)
log:
file: 'web.log' #absolute or relative paths allowed, eg. web.log # Modifying both Scrutiny Backend and Frontend Applications
level: DEBUG If you're developing a feature that requires changes to the backend and the frontend, or a frontend feature that requires real data,
you'll need to follow the steps below:
```
1. install the [Go runtime](https://go.dev/doc/install) (v1.17+)
Once you've created a config file, you can pass it to the scrutiny binary during startup. 2. install [NodeJS](https://nodejs.org/en/download/)
3. create a `scrutiny.yaml` config file
``` ```yaml
go run webapp/backend/cmd/scrutiny/scrutiny.go start --config ./scrutiny.yaml # config file for local development. store as scrutiny.yaml
``` version: 1
Now visit http://localhost:8080 web:
listen:
port: 8080
host: 0.0.0.0
database:
# can also set absolute path here
location: ./scrutiny.db
src:
frontend:
path: ./dist
influxdb:
retention_policy: false
log:
file: 'web.log' #absolute or relative paths allowed, eg. web.log
level: DEBUG
```
4. start a InfluxDB docker container.
```bash
docker run -p 8086:8086 --rm influxdb:2.2
```
5. build the Angular Frontend Application
```bash
cd webapp/frontend
npm install
ng build --watch --output-path=../../dist --prod
# Note: if you do not add `--prod` flag, app will display mocked data for api calls.
```
6. start the scrutiny web server
```bash
go mod vendor
go run webapp/backend/cmd/scrutiny/scrutiny.go start --config ./scrutiny.yaml
```
7. open your browser to [http://localhost:8080/web](http://localhost:8080/web)
If you'd like to populate the database with some test data, you can run the following commands: If you'd like to populate the database with some test data, you can run the following commands:
@ -82,15 +116,6 @@ If you'd like to populate the database with some test data, you can run the fol
docker run -p 8086:8086 --rm influxdb:2.2 docker run -p 8086:8086 --rm influxdb:2.2
docker run --rm -p 8086:8086 \
-e DOCKER_INFLUXDB_INIT_MODE=setup \
-e DOCKER_INFLUXDB_INIT_USERNAME=admin \
-e DOCKER_INFLUXDB_INIT_PASSWORD=password12345 \
-e DOCKER_INFLUXDB_INIT_ORG=scrutiny \
-e DOCKER_INFLUXDB_INIT_BUCKET=metrics \
influxdb:2.2
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/web/testdata/register-devices-req.json localhost:8080/api/devices/register # curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/web/testdata/register-devices-req.json localhost:8080/api/devices/register
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-ata.json localhost:8080/api/device/0x5000cca264eb01d7/smart # curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-ata.json localhost:8080/api/device/0x5000cca264eb01d7/smart
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-ata-date.json localhost:8080/api/device/0x5000cca264eb01d7/smart # curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-ata-date.json localhost:8080/api/device/0x5000cca264eb01d7/smart
@ -105,14 +130,14 @@ curl localhost:8080/api/summary
``` ```
### Collector # Modifying the Collector
``` ```
brew install smartmontools brew install smartmontools
go run collector/cmd/collector-metrics/collector-metrics.go run --debug go run collector/cmd/collector-metrics/collector-metrics.go run --debug
``` ```
## Debugging # Debugging
If you need more verbose logs for debugging, you can use the following environmental variables: If you need more verbose logs for debugging, you can use the following environmental variables:
@ -131,3 +156,16 @@ Finally, you can copy the files from the scrutiny container to your host using t
docker cp scrutiny:/tmp/collector.log collector.log docker cp scrutiny:/tmp/collector.log collector.log
docker cp scrutiny:/tmp/web.log web.log docker cp scrutiny:/tmp/web.log web.log
``` ```
# Docker Development
```
docker build -f docker/Dockerfile . -t chcr.io/analogj/scrutiny:master-omnibus
docker run -it --rm -p 8080:8080 \
-v /run/udev:/run/udev:ro \
--cap-add SYS_RAWIO \
--device=/dev/sda \
--device=/dev/sdb \
ghcr.io/analogj/scrutiny:master-omnibus
/opt/scrutiny/bin/scrutiny-collector-metrics run
```

Write Preview
Loading…
Cancel
Save