Developing#

Development Environment#

SunPeek uses Poetry as a virtual environment and dependency manager and build system. To get started:

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 this repository (or a fork of it, see CONTRIBUTING).
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):

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. On windows enabling WSL2 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 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 runsunpeek/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, 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.

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.