A docker image is built automatically. Docker images can be found under Packages.

This project uses poetry and npm to manage all dependencies. You must install poetry and npm first before running any script.

NOTE: Windows does not support the 'pty' module so invoke commandos fail at windows. If you use windows, you need to install WSL2 and set up a Linux distribution. Then you must install python, poetry and npm on your WSL Remote to run the following commandos.

After cloning the repository, you need to check out the remote dev branch:

git checkout dev

Create a .env file with the following content:

FLASK_APP=muse_for_music
FLASK_DEBUG=1  # to enable autoreload
MODE=debug

Backend:

poetry install

# create the test database
poetry run invoke create-test-db

Start the build process for the frontend:

poetry run invoke start-js

Start the flask dev server

# create test db before first run!

# start flask server
poetry run invoke start-py --autoreload

Drop and recreate DB for local development:

poetry run flask drop_db
poetry run invoke create-test-db

You can also build and run the project in Docker. Under windows you also need WSL2 for that. You need to have a working docker and run the following commandos:

docker build -t m4m .
docker run -it -p8000:8000 m4m

The following sites are available after starting the flask development server:

Web-App User API API

Only in debug mode: debug

The migrations use Flask-Migrate.

The migrations can be run with poetry.

Commands:

# create new migration after model changes:
poetry run flask db migrate

# update db to newest migration:
poetry run flask db upgrade

After creating a new migration file with poetry run flask db migrate it is neccessary to manually check the generated upgrade script. Please refer to the alembic documentation.

# run all tests (WARNING this takes a long time!)
poetry run pytest tests

# run rule based hypothesis test
# the available hypothesis profiles can be found in tests/util.py
poetry run pytest --hypothesis-profile fast ./tests/rule_based_test.py::test_muse_for_music_api

# run tests with coverage
poetry run coverage run --source=muse_for_music --omit='*/debug_routes/*' -m pytest tests

# generate overage reports
poetry run coverage report -m
poetry run coverage html

WARNING: Install script is currently broken!

Prerequisites:

• Python >3.6, Virtualenv, Pip
• npm, node >8
• Apache2, mod-wsgi or another wsgi compatible server

Installation / Upgrade process for installations using apache:

1. Install Prerequisites
2. Download/Clone Repository
3. Copy install.sh to a different location outside of the repository
   1. Make it executable
   2. update the variables at the top of the script
4. execute install.sh

For use with MySql or other db engine:

1. Setup Database User and scheme
   1. For MySql/Mariadb use utf8mb4 charset
2. Install a driver for your selected Database in the virtualenv
3. Update the database url in the config file
   1. For MySql/Mariadb use utf8mb4 charset
4. execute install.sh to generate database

Troubleshooting:

• Check all file permissions (use install.sh as reference)
• Check AppArmor/Selinux permissions
• Check apache logs
• Check apache config
• Check M4M logs
• Check Python version (>3.6!)