Skip to content

Commit

Permalink
docs: more content
Browse files Browse the repository at this point in the history
  • Loading branch information
@karl-cardenas-coding
karl-cardenas-coding committed Jul 6, 2024
1 parent c00835d commit 6fbe9c9
Show file tree
Hide file tree
Showing 3 changed files with 156 additions and 35 deletions.
28 changes: 0 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ MyWhoop is a tool intended to help you take ownership of your Whoop data. You ca
- 🗄️ **Server**: Automatically download your Whoop data daily and save it to a local file or export it to a remote location.
- 📬 **Notifications**: Receive notifications when new data is available or when an error occurs.
- 💾 **Data Export**: Export your Whoop data to a remote location such as an S3 bucket.
-

## Get Started 🚀

Expand All @@ -34,7 +33,6 @@ MyWhoop supports the following commands and global flags:
- [Server](#server) - Automatically download your Whoop data daily and save it to a local file or export it to a remote location.
- [Version](#version) - Display the version of MyWhoop.


#### Global Flags

| Flag | Description | Required | Default |
Expand Down Expand Up @@ -75,31 +73,5 @@ mywhoop login



## Environment Variables

The following environment variables are available for use with MyWhoop.

| Variable | Description | Required |
|---|----|---|
| `WHOOP_CLIENT_ID` | The client ID for your Whoop application. | Yes |
| `WHOOP_CLIENT_SECRET` | The client secret for your Whoop application. | Yes |
| `WHOOP_CREDENTIALS_FILE` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. Default value is `token.json`. | No |


### Notification Variables

Depending on the notification service you use, you may need to provide additional environment variables.

| Variable | Description | Required |
|---|----|---|
| `NOTIFICATION_NTFY_AUTH_TOKEN`| The token for the [Ntfy](https://docs.ntfy.sh/) service. Required if the ntfy subscription requires a token. | No |
| `NOTIFICATION_NTFY_PASSWORD` | The password for the ntfy subscription if username/password authentication is used. Required if the ntfy subscription requires a username and password. | No |

### Order Of Precendence

The order of precendence is as follows.

1. CLI flags.
2. Environment Variables
3. Configuration File

128 changes: 121 additions & 7 deletions docs/configuration_reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,39 @@
# Configuration Reference

The MyWhoop configuration file is used to configure the behavior of MyWhoop and enable advanced features. The configuration file is a YAML file that is located at `~/.mywhoop.yaml` by default. The configuration file can be overridden by using the `--config` flag when issuing MyWhoop commands.
The MyWhoop configuration file is used to configure MyWhoop's behavior and enable advanced features. By default, it is a YAML file located at `~/.mywhoop.yaml`. You can override the configuration file by using CLI flags.


> [!IMPORTANT]
> You can learn more about supported environment variables in the [Environment Variables](./environment_variables.md) section.


## Credentials

The credentials section of the configuration file is used to configure where the MyWhoop authentication token is stored or where to find it. The following fields are available for configuration:

| Field | Description | Required | Default |
|---|----|---|---|
| `credentialsFile` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. By default, MyWhoop looks for a token file in the local directory. | No | `token.json` |

```yaml
credentials:
credentialsFile: "/opt/mywhoop/token.json"
```
## Debug
The debug section of the configuration file is used to enable debug logging for MyWhoop. The following fields are available for configuration:
| Field | Description | Required | Default |
|---|----|---|---|
| `debug` | Enable debug logging. Allowed values are: `INFO`, `DEBUG`, `WARN`, and `ERROR`. | No | `INFO` |


```yaml
debug: "info"
```

## Export

The export section of the configuration file is used to configure the data export feature of MyWhoop. The export feature allows you to export your Whoop data to a remote location such as an S3 bucket. The following fields are available for configuration:
Expand All @@ -23,7 +54,7 @@ Local file export accepts the following fields.
| `fileName` | The name of the file to export. | Yes | `user` |
| `filePath` | The path to save the file. By default, a data folder is created in the immediate folder. | Yes | `data/` |
| `fileType` | The file type to save the file as. Allowed values are `json`. | Yes | `json` |
| `fileNamePrefix` | The prefix to add to the file name. In server mode, the data is automatically inserted as a prefix. | No | |
| `fileNamePrefix` | The prefix to add to the file name. In server mode, the data is automatically inserted as a prefix. | No |`""` |
| `serverMode` | Ensures the file name is unique and contains a timestamp. Ensures behaviors match server mode. | No | `false` |

```yaml
Expand All @@ -38,7 +69,7 @@ export:

### S3 Export

S3 export accepts the following fields.
You can export your Whoop data to an AWS S3 bucket using the S3 export method. By default, AWS credentials are honored from the environment variables or the default profile in the [order of precedence of the AWS SDK](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials). The S3 export method accepts the following fields:

| Field | Description | Required | Default |
|---|----|---|---|
Expand All @@ -60,15 +91,98 @@ export:
fileNamePrefix: ""
serverMode: true
```
## Credentials

The credentials section of the configuration file is used to configure where the Whoop authentication token is stored or where to find it. The following fields are available for configuration:
## Notification

The notification section of the configuration file is used to configure the notification feature of MyWhoop. By default, notifications are sent to stdout. The notification feature allows you to use a different service to receive notifications when MyWhoop completes a task. The following fields are available for configuration:

| Field | Description | Required | Default |
|---|----|---|---|
| `credentialsFile` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. By default, MyWhoop looks for a token file in the local directory. | No | `token.json` |
|`method` | The notification method to use. Allowed values are `ntfy`, or `""`. | Yes | `""`|
| `ntfy` | The ntfy notification configuration. Required if `method` is `ntfy`. | No | |

### Ntfy

You can use the open-source service, [Ntfy](https://docs.ntfy.sh/), to receive notifications when MyWhoop completes a task or an error is encountered. The Ntfy configuration block accepts the following fields:

| Field | Description | Required | Default |
|---|----|---|---|
| `events` | The events to receive notifications for. Allowed values are `""`, `all`, `success`, and `error`. | Yes | `all` |
| `serverEndpoint` | The Ntfy server endpoint to send notifications to. | Yes | `""` |
| `subscriptionID` | The subscription ID to use for the Ntfy subscription. | Yes | `""` |
| `userName` | The username for the Ntfy subscription. Required if user name and password is used. | No | `""` |

```yaml
notification:
method: "ntfy"
ntfy:
serverEndpoint: "https://example.my.ntfy.com"
subscriptionID: "mywhoop_custom_notifications"
events: "all"
```

> [!IMPORTANT]
> Use the environment variables `NOTIFICATION_NTFY_AUTH_TOKEN` or `NOTIFICATION_NTFY_PASSWORD` to provide the Ntfy authentication credentials.



## Server

The server section of the configuration file is used to configure the server feature of MyWhoop. The server feature allows you to start MyWhoop as a server that queries the Whoop API every 24 hours. The following fields are available for configuration:

| Field | Description | Required | Default |
|---|----|---|---|
| `enabled` | Enable the server feature. | No | `false` |
| `firstRunDownload` | Download the data on the first run. This is not a recommended flag for server mode as it will re-download all the Whoop data on a server or machine reboot. | No | `false` |


```yaml
server:
enabled: true
firstRunDownload: false
```


## Example Configuration File


The following is an example configuration file that configures MyWhoop to export data to an S3 bucket, enable the server feature, and send notifications using the Ntfy service.

```yaml
export:
method: s3
awsS3:
region: "us-east-1"
bucket: "42acg-primary-data-whoop-bucket"
fileConfig:
fileName: ""
fileType: "json"
fileNamePrefix: ""
serverMode: true
server:
enabled: true
firstRunDownload: false
notification:
method: "ntfy"
ntfy:
serverEndpoint: "https://ntfy.self-hosted.example"
subscriptionID: "mywhoop_alerts_at_home"
events: "all"
debug: info
```


The following is an example configuration file configuring MyWhoop to export data to a local file and enabling debug logging.

```yaml
export:
method: file
fileExport:
fileName: "user"
filePath: "/opt/mywhoop/data/"
fileType: "json"
fileNamePrefix: ""
credentials:
credentialsFile: "/opt/mywhoop/token.json"
credentialsFile: "/opt/mywhoop/token.json"
debug: debug
```
35 changes: 35 additions & 0 deletions docs/environment_variables.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Environment Variables


MyWhoop uses environment variables to configure the application. The environment variables are used to configure the Whoop API client and other integrations such as notifications.

### Order Of Precendence

The order of precendence is as follows.

1. CLI flags.
2. Environment Variables
3. Configuration File


## MyWhoop Variables

The following environment variables are used to configure MyWhoop. The two required variables are `WHOOP_CLIENT_ID` and `WHOOP_CLIENT_SECRET`.


| Variable | Description | Required |
|---|----|---|
| `WHOOP_CLIENT_ID` | The client ID for your Whoop application. | Yes |
| `WHOOP_CLIENT_SECRET` | The client secret for your Whoop application. | Yes |
| `WHOOP_CREDENTIALS_FILE` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. Default value is `token.json`. | No |


### Notification Variables

Depending on the notification service you use, you may need to provide additional environment variables.

| Variable | Description | Required |
|---|----|---|
| `NOTIFICATION_NTFY_AUTH_TOKEN`| The token for the [Ntfy](https://docs.ntfy.sh/) service. Required if the ntfy subscription requires a token. | No |
| `NOTIFICATION_NTFY_PASSWORD` | The password for the ntfy subscription if username/password authentication is used. Required if the ntfy subscription requires a username and password. | No |

0 comments on commit 6fbe9c9

Please sign in to comment.