https://github.com/cdaringe/freshawair
Host and view your Awair data locally
https://github.com/cdaringe/freshawair
Last synced: 11 months ago
JSON representation
Host and view your Awair data locally
- Host: GitHub
- URL: https://github.com/cdaringe/freshawair
- Owner: cdaringe
- Created: 2020-11-14T19:50:08.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-07-19T02:52:00.000Z (11 months ago)
- Last Synced: 2025-07-19T07:51:55.764Z (11 months ago)
- Language: Rust
- Size: 1.15 MB
- Stars: 25
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# freshawair
Host and view your [Awair data](https://www.getawair.com/) locally.
- **Store** Awair data in your own database
- **View** Awair data from a self hosted web-app (grafana).
## description
`freshawair` is three macro components
- `agent` - captures data from your awair(s) and load data into the database
- `database` - [timescale db](https://www.timescale.com/) instance
- [grafana](https://grafana.com/) - visualize your data
## usage
`docker-compose -f docker-compose.yml -f docker-compose.prod.yml up`
`docker-compose` is the primary supported deployment mechanism. Services may be deployed independently as desired, but users will need to adopt the `docker-compose.yml` configurations into the alternative desired format.
The agent has a CLI with all options configurable via ENV or CLI args:
```sh
$ docker run --rm -it cdaringe/freshawair --help
Usage: agent [OPTIONS] --db-host --db-port
Options:
--awair-endpoint
--db-host
--db-port
--db-user [default: fresh]
--db-password [default: fresh]
--poll-duration-s [default: 60]
-h, --help Print help
-V, --version Print version
```
Postgres/TimescaleDB & Grafana configuration is left to the user. Sensible
defaults are set in compose files.
### local builds
The only supported mechanism for _building_ is following:
- install [rad](https://github.com/cdaringe/rad#install)
- `./rad build`
- `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up`
- visit grafana@[localhost:3000](https://localhost:3000) and select the prebuilt dashboard
See [rad.ts](./rad.ts) or run `rad --list` for various actions.
## Performance
Here are some typical CPU/Mem usage from the different components:
```sh
$ docker stats
NAME CPU % MEM USAGE / LIMIT
freshawair_freshagent_1 0.00% 2.355MiB / 5.641GiB
freshawair_grafana_1 0.05% 38.5MiB / 5.641GiB
freshawair_freshdb_1 0.01% 101.6MiB / 5.641GiB
```
Further tuning can be done to tweak the postgres & grafana runtime characteristics.