hakase

hakase is a collection of helpful utilities for class chatrooms, including an assignment due date reminder, study session scheduler, and more. It is currently under development. This repository holds the main Django backend. A Discord Bot is in development as well, with a Slack App planned in the future.

API Docs and Schema: https://hakase.dragonejt.dev/

Discord Bot: https://github.com/dragonejt/hakase-discord

Table of Contents

• Local Development
  • Building and Running
  • Testing
  • Linting and Formatting
• Deployment
  • Continuous Delivery

Local Development

Building and Running

hakase uses uv for its Python package and virtualenv manager. After installing uv and cloning this repo, you can install dependencies with the command:

uv sync

Local development with hakase is relatively simple. The only command you have to run is:

python manage.py runserver

You do have to have some environment variables in place. hakase does not directly read from a .env file, but you can configure environment variables or reference a .env file through IDE launch options. Otherwise, you can set environment variables locally.

ENV="development"
DEPLOY_HOST="127.0.0.1" # for django allowed hsots
# DATABASE_URL should not be set for local development and testing. A local SQLite instance will be used.
MANAGE_PY_PATH="manage.py" # to register django tests in VS Code

Testing

For testing, the following command should be run, with the above environment variables in place:

python manage.py test

This uses Django's test runner which executes all unit tests found in the various tests.py files in each app. The integrate.yml GitHub Actions workflow will run these tests.

If you want to use the VS Code test runner, alongside setting the MANAGE_PY_PATH environment variable you also have to enable Python unit testing with the unittest framework and configure the setting "python.experiments.optInto": ["pythonTestAdapter"].

Linting and Formatting

hakase uses ruff as its Python linter and code formatter. To lint and format your code, run the following commands:

ruff check --fix
ruff format

The integrate.yml GitHub Actions workflow will check for linting errors and formatting mistakes.

Deployment

For deployment, hakase is built into a Docker image with nixpacks, and then deployed into a container via Dokku. Migrations, static file collection, and deployment checks are all done as a part of the release task, and the web container uses gunicorn to run the web server. The Procfile contains more details about the commands run as a part of deployment.

On the deployed docker container, the following environment variables should be set:

ENV="production" # sets DEBUG setting
DEPLOY_HOST="production domain name"
DATABASE_URL="parsed by dj-database-url"

Dokku does support dockerized databases, and hakase uses a Dockerized PostgreSQL DB in production.

Continuous Delivery

hakase has a continuous delivery GitHub Actions workflow, deliver.yml. The steps taken are summarized:

1. Build a Docker image with the nixpacks GitHub Action
2. The nixpacks GitHub Action uploads the built image to GitHub Container Registry
3. The built docker image is deployed as a docker container via the Dokku GitHub Action
4. Dokku runs the web and release tasks in the Procfile, performs healthchecks, and replaces the old container.
5. A new Sentry release is created for monitoring with the Sentry Release GitHub Action.