This document contains additional information on contributing to dribdat as a developer. If you are just interested in connecting to dribdat's API, scroll down to the API overview
For more background references, see the README.
This code is originally based on cookiecutter-flask, which has a number of helpful developer features. It is a Python 3 project that uses the Flask microframework and SQLAlchemy for data modelling on the backend. A plain JSON API, along with Jinja templates and WTForms, serves data to a frontend based on Bootstrap 3 and jQuery.
Install Python (3.7+), Virtualenv and Pip, or Poetry to start working with the code.
You may need to install additional libraries (
libffi) for the misaka package, which depends on CFFI, e.g.
sudo dnf install libffi-devel
Run the following commands from the repository root folder to bootstrap your environment:
poetry shell poetry install
Or using plain pip:
pip install -r requirements/dev.txt
By default in a dev environment, a SQLite database will be created in the root folder (
dev.db). You can also install and configure your choice of DBMS supported by SQLAlchemy. In production, the
DATABASE_URL configures connectivity to an SQLAlchemy-compatible database engine. This requires a
.envto store environment variables for local development. See the Configuration section for more details.
Run the following to create your local SQLite database tables and perform the initial migration. Note that we avoid using the production
migrations folder locally due to Flask-Migrate#61:
mv migrations migrations_prod python manage.py db init python manage.py db migrate python manage.py db upgrade
Install a local copy of frontend resources for offline development using yarn install. These will be used when
FLASK_ENV=dev, otherwise a CDN will be used in production.
Finally, run this command (or just
debug.sh) to start the server:
FLASK_DEBUG=1 python manage.py run
You will see a welcome screen at http://127.0.0.1:5000 - register your first user account, which will have admin access and let you set up events.
This section has some advice for developers and operators.
To open the interactive shell, run:
python manage.py shell. By default, you will have access to the
User model, as well as Event, Project, Category, Activity.
Using the Heroku toolchain,
heroku run python manage.py shell, or using Docker,
docker-compose run --rm dribdat python manage.py shell.
To run all tests, whose source is in the tests folder, run:
python manage.py test
To run just a specific test, specify it by name, e.g.
python manage.py test --name features
Whenever a database migration needs to be made. Run the following commands:
python manage.py db migrate
This will generate a new migration script. Then run:
python manage.py db upgrade
To apply the migration. Watch out for any errors in the process.
For a full migration command reference, run
python manage.py db --help.
There are a number of API calls that admins can use to easily get to the data in Dribdat in various formats. The full list of calls is shown in the About or Search page in a running app. For example, to get basic data on an event:
To search all project contents:
limit query parameter to get more or less than 10 results.
If you would like to use external clients, like the chatbot, to remote control Dribdat you need to set
DRIBDAT_APIKEY. The (experimental) call used to push data into projects is:
For more details see api.py