Pipeline Status Test Coverage Supported Python GitLab contributors Open Issues

SunPeek Backend#

You are currently looking at the code of the SunPeek Backend, responsible for SunPeek’s Python API and REST API. If you just want to use SunPeek, please visit the SunPeek Documentation.

Contributions#

We welcome contributions of all kinds, including issues, comments, and merge requests. Please see our Contribution Guidelines for details.

License#

License details can be found in the LICENSE file.

Developer Guide#

Installation#

SunPeek Python uses Poetry as a virtual environment and dependency manager and build system.

1. Set up Poetry#

Install poetry

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
Clone (or fork) this repository.
Open a terminal in the repository root and run poetry install --with dev. This will create a Python virtual environment with all the required dependencies.

Note

If you get errors from poetry, try running poetry lock, then poetry install --with dev again.

Tip

If you are using PyCharm as your IDE, make sure you have version 2022.3 or newer, then follow these instructions to set up PyCharm to work with the Poetry virtual env. You may need to restart PyCharm after installing poetry.

2. Set up .env file#

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):

HIT_DB_TYPE=sqlite
HIT_DB_HOST=//sunpeek_db_test.sqlite

Run SunPeek#

The entrypoint.py file allows you to run the SunPeek API. In the root directory, please open a console and run:

   python entrypoint.py

In PyCharm you can also do this by right-clicking entrypoint.py and clicking on Run. This command will also initialize your database. After this, you should be able to see the API documentation at http://localhost:8000/docs

You can verify that the API is working by trying out the following routes:

verify the API is listening http://localhost:8000/config/ping_backend?token=harvestIT
verify the database is listening http://localhost:8000/config/ping_database?token=harvestIT

To use breakpoints and other debugging features while testing the REST API, you can run the file entrypoint.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/docs.

Testing with pytest#

SunPeek Python uses pytest to check that the code works as expected. The tests may also serve as examples on how the code may be used. For developing and bug fixing, please always include tests checking that the desired behavior is met.

To run all tests, use:

python -m pytest --cov-config=.coveragerc --cov=./ ./tests/

If you are working in PyCharm, you can also right-click on the /tests directory and click on Run 'pytests in tests'.

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, which can detect most 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.

Create the “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.

Debugging with Frontend (Docker)#

In order to debug the backend with the web-ui running, a Docker Compose configuration is provided. However, this means that Docker needs to be installed!

Install Docker

Linux

To install Docker on Linux go to https://docs.docker.com/engine/install/ select the relevant platform and follow the instructions.

Windows 10 and 11

On desktop Windows, the easiest way to get Docker is to install Docker Desktop. Enabling WSL2 is recommended, but Docker Desktop should work without it.

Windows Server

To install the Docker Engine on Windows Server, see this guide from Microsoft
Set up SunPeek Docker Image

(Please ensure Docker is running) From a terminal in the root of this repository, simply run:

Linux
```
 cd ./dev-utils
 ./debug-env.sh
```
Windows
```
 cd ./dev-utils
 .\debug-env.bat
```
In case you get the error unable to get image 'sunpeek/web-ui' at docker compose up -d, please make sure that Docker Desktop is started. This command may take 30 seconds or so to complete.
Debugging

After steps 1 and 2, you can run entrypoint.py, e.g., with a debugger attached. In PyCharm, for example, right-click on that file and select Debug, then access the WebUI at http://localhost:8080.

Debugging with Frontend (JS-Code)#

You can also debug the Python code and the JavaScript code of the frontend together. The instructions for this can be found in SunPeek’s WebUI repository.