# Developer Docs
## Development Environment
SunPeek uses [Poetry](https://python-poetry.org/) as a virtual environment and dependency manager and build system. To 
get started:
1. [install poetry](https://python-poetry.org/docs/#installation)  
  ```{note}
  You may need to allow powershell to run scripts (for example to use the built-in terminal in PyCharm on Windows). 
  To do this, go to the start menu, search powershell, right click and select run as administrator. In the terminal that 
  opens run `set-executionpolicy remotesigned`
  ```
2. Clone this repository (or a fork of it, see [CONTRIBUTING](https://gitlab.com/sunpeek/sunpeek/-/blob/main/CONTRIBUTING.md)).
3. Open a terminal in the repository root and run `poetry install --with dev`. This will get you a python virtual environment 
with all the required dependencies. If you get errors from poetry, try running `poetry lock`, then `poetry install --with dev` again.

In order for some debugging operations to work, you will need an environment file to set certain configuration options; 
create a file called `.env` in the root of the repository, and add the following lines (for a default configuration):

```dotenv
HIT_DB_TYPE=sqlite
HIT_DB_HOST=//sunpeek_db_test.sqlite
```

```{tip}  
The instructions in several of the following sections assume you have docker installed. On most desktop OSs, you can do 
this with [Docker Desktop](https://www.docker.com/products/docker-desktop/).
On windows [enabling WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) is recommended, but docker desktop should work without it.
```
```{tip}  
If you are using PyCharm as your IDE, make sure you have version 2022.3 or newer, then follow [these instructions](https://www.jetbrains.com/help/pycharm/poetry.html)
to set up PyCharm to work with the Poetry virtual env. You may need to restart PyCharm after installing poetry.
```

## Running the application in the development environment
### Run directly in a local terminal
In a terminal window with the correct virtual environment active, run: `uvicorn sunpeek.api.main:app --reload`

### Run standalone in Docker 
Pull and run the latest image from the Docker Hub image registry: `docker run -p 8000:8000 --name sunpeek sunpeek/sunpeek:latest`

## Debugging the HTTP API
In order to use breakpoints etc. while testing the REST API, you can run the file api/main.py with a debugger attached, 
following whatever your normal procedure for running a python script with an attached debugger is (in PyCharm, right 
click on api/main.py and select "Debug"). The API is then accessible at http://localhost:8000. 

In order to debug the backend with the web-ui running, a docker compose configuration is provided, from a terminal in 
the root of this repository, simply run `cd ./dev-utils`, then `./debug-env.sh` on Linux and Mac or `.\debug-env.bat` on
windows. This command may take 30 seconds or so to complete, after which you can run`sunpeek/api/main.py` with a 
debugger attached (for example in PyCharm, right-click on that file and select Debug), then access the Web-UI at 
http://localhost:8080.

## Database Migrations
So that users can update from one version to the next without losing data, it is important that any changes to the
database schema are accompanied by database migrations, which update existing user databases to match the new schema.
In order to support this, we use [Alembic](https://alembic.sqlalchemy.org/en/latest/), which can detect 
[_most_](https://alembic.sqlalchemy.org/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect) 
changes made on our ORM classes and automatically generate migration files. The convenience script 
`alembic/create_migrations.sh` can be used to create a migration file in `alembic/versions` which _**must**_ be manually
checked by the developer who made changes to the ORM models, to see if the generated migrations match the intent of the 
code changes. In order to support users downgrading, developers should check both the upgrade and downgrade functions. 
The migrations can be tested with `alembic/test_migrations.sh`. You will need to have docker available for these scripts
to work.

## Installer package
The installer package can be generated by running `pyinstaller .\sunpeek_easy_installer.spec --distpath=.`, on Windows, then 
zipping the resulting sunpeek_easy_installer folder. Note that there is no automated testing for this process.