Jazztunes is a web app that helps jazz musicians manage their repertoire. To use it, go to jazztunes.org.
This readme focuses on technical aspects of the app of interest to developers; for a user manual, see here.
Jazztunes is a full-stack web app built using Django 5.2 on the back end and htmx on the front end with Tailwind CSS for styling. The database is PostgreSQL. Tables are implemented with DataTables for clickable column sorting. Tests are written in pytest and Playwright. The deployed version uses Python 3.13, but it should work on Python 3.11 or later.
ERD coming soon!
Follow these instructions if you want to run jazztunes locally or develop it. Otherwise, the easiest way to use it is at jazztunes.org.
Note: these instructions assume you are using uv for project management.
- Clone this repository.
- Navigate to the
jazztunesdirectory. - Copy the contents of
env-templateinto a file named.envin the project's root directory.env-templatecontains reasonable default values, but change them as needed. - Install dependencies:
uv sync. - Set up the database:
uv run python manage.py migrate. - If you want to use the Public tune feature, you'll need to create a superuser:
uv run python manage.py createsuperuser, then set that user's ID to ADMIN_USER_ID in.env(it will be 1 if it's the first user created, otherwise 2, etc.). Tunes you create as the superuser will show up on the Public page for all other users. Creating a superuser is also a good idea because it gives you access to the Django admin interface. - Start the server:
uv run python manage.py runserver - Ctrl-click on
http://127.0.0.1:8000— This will open jazztunes in your default browser. You can also just navigate to that address in a browser. - You can close the program by closing your browser and pressing
Ctrl-Cin the terminal running the server.
Jazztunes includes unit tests written in pytest and end-to-end tests which use Playwright. If you are contributing to Jazztunes, please (1) run the tests, to make sure your contributions don't break anything; and (2) write tests covering your contribution, if applicable. Or perhaps you'd just like to contribute some tests! Tests can be found in the tests directory at the root of the project.
Run all the tests:
uv run pytest
Run only the unit tests:
uv run pytest -k unit
Note: the -k option can be used to match any pattern in directory, file, or test names!
Run the tests in "headed" mode (for end-to-end tests only -- a browser will open and you can watch it go through the steps):
uv run pytest -k e2e --headed
See the respective docs for many more options when running tests.
Jazztunes is free software, released under version 3.0 of the GPL. Everyone has the right to use, modify, and distribute jazztunes subject to the stipulations of that license.