You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
189 lines
6.6 KiB
189 lines
6.6 KiB
# Contributing
|
|
|
|
The Scrutiny repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing source code for:
|
|
- Scrutiny Backend Server (API)
|
|
- Scrutiny Frontend Angular SPA
|
|
- S.M.A.R.T Collector
|
|
|
|
Depending on the functionality you are adding, you may need to setup a development environment for 1 or more projects.
|
|
|
|
# Modifying the Scrutiny Backend Server (API)
|
|
|
|
1. install the [Go runtime](https://go.dev/doc/install) (v1.20+)
|
|
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`
|
|
3. create a `scrutiny.yaml` config file
|
|
```yaml
|
|
# config file for local development. store as scrutiny.yaml
|
|
version: 1
|
|
|
|
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. start the scrutiny web server
|
|
```bash
|
|
go mod vendor
|
|
go run webapp/backend/cmd/scrutiny/scrutiny.go start --config ./scrutiny.yaml
|
|
```
|
|
6. open your browser to [http://localhost:8080/web](http://localhost:8080/web)
|
|
|
|
# Modifying the Scrutiny Frontend Angular SPA
|
|
|
|
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:
|
|
|
|
1. install [NodeJS](https://nodejs.org/en/download/)
|
|
2. start the Angular Frontend Application
|
|
```bash
|
|
cd webapp/frontend
|
|
npm install
|
|
npm run start -- --serve-path="/web/" --port 4200
|
|
```
|
|
3. open your browser and visit [http://localhost:4200/web](http://localhost:4200/web)
|
|
|
|
# Modifying both Scrutiny Backend and Frontend Applications
|
|
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.20+)
|
|
2. install [NodeJS](https://nodejs.org/en/download/)
|
|
3. create a `scrutiny.yaml` config file
|
|
```yaml
|
|
# config file for local development. store as scrutiny.yaml
|
|
version: 1
|
|
|
|
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
|
|
npm run build:prod -- --watch --output-path=../../dist
|
|
# 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:
|
|
|
|
> NOTE: you may need to update the `local_time` key within the JSON file, any timestamps older than ~3 weeks will be automatically ignored
|
|
> (since the downsampling & retention policy takes effect at 2 weeks)
|
|
> This is done automatically by the `webapp/backend/pkg/models/testdata/helper.go` script
|
|
|
|
```
|
|
docker run -p 8086:8086 --rm 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/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-date2.json localhost:8080/api/device/0x5000cca264eb01d7/smart
|
|
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-fail2.json localhost:8080/api/device/0x5000cca264ec3183/smart
|
|
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-nvme.json localhost:8080/api/device/0x5002538e40a22954/smart
|
|
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-scsi.json localhost:8080/api/device/0x5000cca252c859cc/smart
|
|
# curl -X POST -H "Content-Type: application/json" -d @webapp/backend/pkg/models/testdata/smart-scsi2.json localhost:8080/api/device/0x5000cca264ebc248/smart
|
|
go run webapp/backend/pkg/models/testdata/helper.go
|
|
|
|
curl localhost:8080/api/summary
|
|
|
|
```
|
|
|
|
# Modifying the Collector
|
|
```
|
|
brew install smartmontools
|
|
go run collector/cmd/collector-metrics/collector-metrics.go run --debug
|
|
```
|
|
|
|
|
|
# Debugging
|
|
|
|
If you need more verbose logs for debugging, you can use the following environmental variables:
|
|
|
|
- `DEBUG=true` - enables debug level logging on both the `collector` and `webapp`
|
|
- `COLLECTOR_DEBUG=true` - enables debug level logging on the `collector`
|
|
- `SCRUTINY_DEBUG=true` - enables debug level logging on the `webapp`
|
|
|
|
In addition, you can instruct scrutiny to write its logs to a file using the following environmental variables:
|
|
|
|
- `COLLECTOR_LOG_FILE=/tmp/collector.log` - write the `collector` logs to a file
|
|
- `SCRUTINY_LOG_FILE=/tmp/web.log` - write the `webapp` logs to a file
|
|
|
|
Finally, you can copy the files from the scrutiny container to your host using the following command(s)
|
|
|
|
```
|
|
docker cp scrutiny:/tmp/collector.log collector.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
|
|
```
|
|
|
|
|
|
# Running Tests
|
|
|
|
```bash
|
|
docker run -p 8086:8086 -d --rm \
|
|
-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 \
|
|
-e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=my-super-secret-auth-token \
|
|
influxdb:2.2
|
|
go test ./...
|
|
|
|
```
|