proCAT

A Django web app for hosting the Project Charging and Analytics Tool (ProCAT).

This Django project uses:

• pip-tools for packaging and dependency management.
• pre-commit for various linting, formatting and static type checking.
  • Pre-commit hooks are automatically kept updated with pre-commit.ci.
• pytest and GitHub Actions.

Installation

To get started:

1. Activate a git repository (required for pre-commit and the package versioning with setuptools-scm):

   git init

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate # with Powershell on Windows: `.venv\Scripts\Activate.ps1`

3. Install development requirements:

   pip install -r dev-requirements.txt

4. (Optionally) install tools for building documentation:

   pip install -r doc-requirements.txt

5. Install the git hooks:

   pre-commit install

6. Run the web app:

   python manage.py runserver

   When running the webapp for the first time you may get a warning similar to:

   You have 19 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, main, sessions.

   If this is the case, stop your webapp (with CONTROL-C) and apply the migrations with:

   python manage.py migrate

   then restart it.

7. Run the tests:

   pytest

8. Create an admin account to access admin backend:

   python manage.py createsuperuser

Installation with Docker

The app can be run within a Docker container and a docker-compose.yml file is provided to make this easy for development.

Ensure you have Docker installed and simply run:

docker compose up

The app will be available at http://127.0.0.1:8000/

Updating Dependencies

To add or remove dependencies:

1. Edit the dependencies variables in the pyproject.toml file (aim to keep development tools separate from the project requirements).
2. Update the requirements files:
   • pip-compile for requirements.txt - the project requirements.
   • pip-compile --extra dev -o dev-requirements.txt for the development requirements.
   • pip-compile --extra doc -o doc-requirements.txt for the documentation tools.
3. Sync the files with your installation (install packages):
   • pip-sync *requirements.txt

To upgrade pinned versions, use the --upgrade flag with pip-compile.

Versions can be restricted from updating within the pyproject.toml using standard python package version specifiers, i.e. "black<23" or "pip-tools!=6.12.2"