Metadata-Version: 2.1
Name: bmonreporter
Version: 0.0.13
Summary: Creates Energy Reports from BMON Servers.
Home-page: https://github.com/alanmitchell/bmonreporter
Author: Alan Mitchell
Author-email: tabb99@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pyyaml (>=5.1.1)
Requires-Dist: awscli (>=1.16.264)
Requires-Dist: papermill (>=1.2.0)
Requires-Dist: nteract-scrapbook (>=0.3.1)
Requires-Dist: jupyterthemes (>=0.20.0)

# bmonreporter

This script creates the "Energy Reports" for 
[BMON Building Monitoring](https://github.com/alanmitchell/bmon) applications.
It is meant to be run periodically; it is currently run once per day at 3 am
and utilizes an AWS EC2 server to run the script.  The script is generally
configured to store the final produced reports in an web-accessible AWS S3 bucket, which is
then accessed by the BMON application to allow users to view the reports.
The 'ENERGY_REPORTS_URL' in the BMON settings file points at the URL of the
S3 bucket.

Reports are generated by running Jupyter Notebooks that produce the graphs, tables, and text
that make up the report.  Notebooks can be run at the "building" level or the "organziation" level.
A Building notebook is run for every building on a BMON server.  Organization notebooks are
run for each Organization.  The report notebooks are stored in Git repositories along with some
additional configuration information that indicates which BMON sites to run reports against.
[Here is an example of a Git repository](https://github.com/alanmitchell/bmonreporter-templates)
that contains suitable Jupyter Notebooks and configuration info.

The configuration of this `bmonreporter` script is done with a YAML configuration
file, patterned after [this sample configuration file](https://github.com/alanmitchell/bmonreporter/blob/master/bmonreporter/main_config_example.yaml).
The main purpose of the configuration file is to identify the Git repositories containing
Jupyter Notebooks to process.  Multiple Git repositories can be processed by one run of `bmonreporter`.

`bmonreporter` runs with Python 3.7+ and is installed by:

```bash
pip install bmonreporter
```

The server where `bmonreporter` is installed must have all of the Python
packages used by the Jupyter Notebooks that are processed from the targeted
Git repositories.  Also, reports produced by `bmonreporter` and the log files
for the script are generally stored in AWS S3 buckets.  So, the server must
have suitable priveleges to write to those buckets.  `bmonreporter` uses the
AWS command line utility to store files into S3 buckets.  This utility is installed
when `bmonreporter` is installed, but the utility must be configured according to
[this page](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html),
and this configuration process will configure proper credentials for writing to S3 buckets.

Use of `bmonreporter` just involves running the script with a command line argument
pointing to the configuration file:

```bash
bmonreporter <path to configuration file>
```
for example:
```bash
bmonreporter /home/joeuser/config.yaml
```


