Metadata-Version: 2.1
Name: sunpeek
Version: 0.2.30
Summary: Large Solar Thermal Monitoring Tool. Implements the Performance Check Method of ISO 24194
Home-page: https://gitlab.com/sunpeek/sunpeek
License: LGPL-3.0-only
Keywords: solarthermal,solar,energy,monitoring
Author: Philip Ohnewein, Daniel Tschopp, Lukas Feierl, Marnoch Hamilton-Jones, Jonathan Cazco
Maintainer: Marnoch Hamilton-Jones
Maintainer-email: m.hamilton-jones@aee.at
Requires-Python: >=3.8,<3.9
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering
Provides-Extra: all
Provides-Extra: api
Provides-Extra: db
Provides-Extra: demo
Requires-Dist: coolprop (>=6.4,<6.5)
Requires-Dist: fastapi (>=0.92) ; extra == "api" or extra == "all"
Requires-Dist: httpx ; extra == "api" or extra == "all"
Requires-Dist: kaleido (==0.2.1)
Requires-Dist: lxml
Requires-Dist: metpy
Requires-Dist: numpy
Requires-Dist: onnx (==1.13.1)
Requires-Dist: onnxruntime
Requires-Dist: orjson
Requires-Dist: pandas (>=2,<3)
Requires-Dist: pendulum
Requires-Dist: pint (==0.20.1)
Requires-Dist: pint-pandas (>=0.2)
Requires-Dist: protobuf (<4)
Requires-Dist: psycopg2-binary ; extra == "db" or extra == "api" or extra == "all"
Requires-Dist: pvlib
Requires-Dist: pydantic (>=1.10.5,<2.0.0)
Requires-Dist: pyephem
Requires-Dist: pyproj (<3.5.0)
Requires-Dist: python-dotenv
Requires-Dist: python-multipart ; extra == "api" or extra == "all"
Requires-Dist: scikit-learn (<1.2)
Requires-Dist: scipy (>=1.10)
Requires-Dist: skl2onnx (==1.13)
Requires-Dist: sqlalchemy (>=1.4,<2.0)
Requires-Dist: sqlalchemy-utils
Requires-Dist: statsmodels
Requires-Dist: sunpeek-exampledata (>=0.1.0) ; extra == "demo" or extra == "all"
Requires-Dist: times
Requires-Dist: timezonefinder
Requires-Dist: tomli (>=2.0.1,<3.0.0)
Requires-Dist: trio
Requires-Dist: uvicorn[standard] (<0.18) ; extra == "api" or extra == "all"
Requires-Dist: yamlloader
Project-URL: Documentation, https://docs.sunpeek.org
Project-URL: Repository, https://gitlab.com/sunpeek/sunpeek
Description-Content-Type: text/markdown

![Logo_Transparent_wide.svg](https://gitlab.com/sunpeek/sunpeek/-/raw/main/static_assets/Logo_Transparent_wide.svg?inline=false)

**Core:**

![Pipline Status](https://gitlab.com/sunpeek/sunpeek/badges/main/pipeline.svg) 
![Test Coverage](https://gitlab.com/sunpeek/sunpeek/badges/main/coverage.svg) 
![Supported Python](https://img.shields.io/pypi/pyversions/sunpeek)
[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/sunpeek/sunpeek?label=image&logo=docker&sort=semver)](https://hub.docker.com/r/sunpeek/sunpeek)
[![PyPI](https://img.shields.io/pypi/v/sunpeek?logo=PyPi&logoColor=yellow)](https://pypi.org/project/sunpeek/)
![GitLab contributors](https://img.shields.io/gitlab/contributors/sunpeek/sunpeek)
![Open Issues](https://img.shields.io/gitlab/issues/open-raw/sunpeek/sunpeek?gitlab_url=https%3A%2F%2Fgitlab.com) 

**WebUI:**

![Pipline Status](https://gitlab.com/sunpeek/web-ui/badges/main/pipeline.svg)
[![Docker Image Version (latest by date)](https://img.shields.io/docker/v/sunpeek/web-ui?label=image&logo=docker)](https://hub.docker.com/r/sunpeek/sunpeek)
![GitLab contributors](https://img.shields.io/gitlab/contributors/sunpeek/web-ui)
![Open Issues](https://img.shields.io/gitlab/issues/open-raw/sunpeek/web-ui?gitlab_url=https%3A%2F%2Fgitlab.com) 

# About SunPeek
SunPeek implements a dynamic, in situ test methodology for large solar thermal plants, packaged as an open source software 
application and python library. It also includes the first open source implementation of the ISO 24194 procedure 
for checking the yield of solar thermal collector fields

Full documentation is at [https://docs.sunpeek.org](https://docs.sunpeek.org)

SunPeek was originally developed as part of the HarvestIT research project, see [https://www.collector-array-test.org](https://www.collector-array-test.org)

## A Web Application and a Python Library
SunPeek is available as both a complete, containerised web application - intended to make the ongoing monitoring of one or
several solar thermal plants simple and intuitive - and as a python library, for use by researchers and for building into 
other tools. To install the python library, simply run `pip install sunpeek`. To set up the web application, see below.

## License
Except where specifically noted otherwise, SunPeek is made available under the GNU Lesser General Public License. This means
that you can use the software, copy it, redistribute it and include it in other software, including commercial, proprietary 
software, for free, as long as you abide by the terms of the GNU GPL, with the exceptions provided by the LGPL. In particular, 
if you redistribute a modified version of the software, you must make the source code of your modifications available, and
if you include the software in another piece of software or physical product, you must give users notice that SunPeek is 
used, and inform them where to obtain a copy of the SunPeek source code and license.

Note that the SunPeek WebUI (https://gitlab.com/sunpeek/web-ui), is covered by a seperate licence, the BSD-3-Clause, see:
https://opensource.org/licenses/BSD-3-Clause

Copyright (c) 2020-2022, AEE - Institut für Nachhaltige Technologien, SOLID Solar Energy Systems GmbH, GASOKOL GmbH, Schneid Gesellschaft m.b.H.  
Copyright (c) 2023, SunPeek Open Source Contributors

SunPeek is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 

# Running SunPeek
## Linux
The preferred way to run the SunPeek application is with docker on a Linux host. Running on Docker on Windows ([see below](#windows)) 
or installing directly on the host (not recommended) is also possible. 

## Deploy Full Application with Docker Compose
The full application can be run with docker compose. This requires docker engine 19.03+, supporting the `docker compose`
command (instead of the older separate `docker-compose` tool). Use `docker version` to check. To install docker go to
https://docs.docker.com/engine/install/ select the relevant platform and follow the instructions.

1. Use https://gitlab.com/api/v4/projects/43333900/repository/archive?path=deploy to download an archive of the 
deployment files and unzip it to the location you want to run it from.
2. Open `api.env.template` and set `HIT_DB_PW` to a strong random password
3. Open `db.env.template` and set `POSTGRES_PASSWORD` to _the same_ strong random password.
4. If you want to access the application from anywhere except the local machine, open `ui.env.template` and replace `localhost`
in `HIT_API_BASE_URL` with a URL which can be used to access the machine on which the application is running. **IMORTANT:
it is strongly recommended that you don't make SunPeek accessible from the public internet. At present there are NO built
in access controls**
5. In a terminal in the unzipped folder, run `docker compose up -d`
6. After at most 2 minutes (usually a few seconds), the web UI should be accessible at http://localhost, or the url set 
in step 4.

## Windows
### Get Docker
#### Windows 10 and 11
On desktop windows, the easiest way to get Docker is to install [docker desktop](https://www.docker.com/products/docker-desktop/).
#### Windows server 
To install the Docker Engine on Windows Server, see [this guide from Microsoft](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce)

### Set up SunPeek
##### Using the Easy Installer
For convenience, if you wish to avoid using powershell, a simple graphical utility is provided for use on Windows. 
Docker is still required. **NOTE: If you have previously set up SunPeek using the default configuration, you must first 
remove all stored data by running the command `docker volume rm harvestit_hit_postgres_data`, _this will also remove 
uploaded data._ You do not need to do this to update the software, simply open a command prompt in the folder where you 
stored the SunPeek configuration and run `docker compose pull`, then `docker compose up -d`**
1. Download [this file](https://gitlab.com/sunpeek/sunpeek/-/raw/main/sunpeek_easy_installer.zip?inline=false), and unzip
it to a temporary location.
2. Run `sunpeek_easy_installer.exe`
3. You should then get a small window with 2 fields. You must select a location to store the configuration files for the
application, if you are running the application only for access from the local machine, leave the default in the url field. 
4. Click setup. 
5. Once the window closes open the directory you specified, and double-click the start.bat file. A command prompt will 
open to display the startup process.
6. Docker compose will download the required application components, this may take several minutes, once you see all 
components listed as 'started' or 'healthy' you can close the command prompt.
7. Open a browser and go to the url specified in the setup tool, probably http://localhost to see the web-UI for the tool.
8. To stop the application, assuming no other processes are running under docker on your machine, simply shut down the 
docker engine. If you are using Docker Desktop, this can be done by right clicking the Docker icon the the system try and 
selecting Quit

## Configuration
Configuration is via environment variables, which can be set by any configuration management system you use, however the
default setup uses `.env` files. To deploy the application on a single host, only the database password and external URL
need to be set. The easy installer does this for you, or you can manually set the value of 
`HIT_DB_PW` and `POSTGRES_PASSWORD` in the `api.env` and `db.env` files to *the same* random, unique password string, 
and the value of `HIT_API_BASE_URL` in the `ui.env` file to <external.url>/api/v1. Other configuration variables are 
documented at [docs.sunpeek.org/configuration-variables.html](https://docs.sunpeek.org/configuration-variables.html) 
_*NOTE*_: This setup is designed to deploy all containers on a single machine where docker compose is running. 
The configuration for the Traefik reverse proxy is stored in a directory which is *bind mounted* to the container. For 
other deployment approaches (e.g. using Kubernetes), a more appropriate Traefik dynamic 
[configuration provider](https://doc.traefik.io/traefik/providers/overview/) should be selected.

## Upgrading to a new version of SunPeek
Updates to SunPeek are accomplished by pulling newer versions of the docker images used to run the application. These 
are used to create new containers in place of the old ones. If you used the default configuration, a persistent docker 
volume called `sunpeek_postgres_data` will have been created, this _should_ avoid data loss, however keeping backups is 
always recommended. The update process is as follows, and is the same on all operating systems:
1. Open a terminal/command prompt in the configuration folder selected during setup.
2. Run `docker compose pull` to download the latest images
3. Run `docker compose up -d` to recreate any containers which have updated images.

## Technical Details - What does compose do?
[Docker Compose](https://docs.docker.com/compose/) is a tool for *orchestrating* docker containers, to create 
applications made up of several docker containers. When the HarvestIT application is started with the default docker-compose 
file, the following things happen:
1. Compose checks if each of the images defined in the compose file, is available with the correct tag locally, if not it
pulls them from the relevant registry
2. A virtual network is created, for the containers to communicate with each other. This is segregated from the host machine's
main network interfaces.
3. The database container (using image `timescale/timescaledb:latest-pg14`), is started, with a healthcheck defined. 
Alongside this container, a [Docker Volume](https://docs.docker.com/storage/volumes/) is created called `hit_postgres_data`, 
which is mapped to the default data directory in the database container, to ensure that database data is persisted when 
the containers are recreated (e.g. during an update).
4. The reverse proxy container (using image `traefik:v2.8`) is started. As well as being attached to the virtual network 
created by docker compose, this has port 80 exposed to the host, so that it can be accessed at `localhost/` or from an
extrnal connection. This routes web requests to either the web-ui or api containers, depending on the path in the request 
URL. It can also [be configured](https://doc.traefik.io/traefik/https/overview/) to terminate TLS (HTTPS) encrypted 
connections and obtain certificates automatically, to secure connections to the application.
5. Compose waits until the database container reports a "healthy" status, then starts the api container (using image 
`sunpeek:latest)`, this is the main HarvestIT application.
6. The `harvestit` container runs a database initialization scripts to get the database ready. 
7. Once the api container has started, the webui container is started. 

# Developing
For information on contributing to sunpeek, see CONTRIBUTING.md, for developer documentation see 
[https://docs.sunpeek.org/developing.html](https://docs.sunpeek.org/developing.html)

# Maintainers and Steering Committee
SunPeek is developed as an open source project, with contributions gladly accepted from interested members of the community.
The overall direction of the project is managed by a **steering committee**, which currently consists of: 
* Daniel Tschopp <d.tschopp@aee.at>
* Philip Ohnewein <p.ohnewein@aee.at>
* Marnoch Hamilton-Jones <m.hamilton-jones@aee.at>
* Lukas Feierl <l.feierl@solid.at>
* Maria Moser <m.moser@solid.at>

The steering committee appoints the project maintainers, and makes final decisions on which contributors have commit 
privileges on the official repository as well as ongoing implementation of new features and updates. The maintainers are
responsible for reviewing and merging any merge (pull) requests. The current **maintainers** are:
* Marnoch Hamilton-Jones <m.hamilton-jones@aee.at>
* Lukas Feierl <l.feierl@solid.at>
* Philip Ohnewein <p.ohnewein@aee.at>

