Project Charging and Analytics Tool (proCAT)

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

This Django project uses:

• uv 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. This creates a .venv in the same directory with the environment, including the dev dependencies:

   uv sync

3. (Optionally) install tools for building documentation:

   uv sync --group doc

4. Install the git hooks:

   pre-commit install

5. 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.

6. Run the tests:

   pytest

7. Create an admin account to access admin backend:

   python manage.py createsuperuser

Login, SSO and local accounts

During development, local accounts are enabled but links in the front page will try to login you via Imperial's Single Sign On (SSO) and it will fail unless you have all the connection details configured - ask for details to the HoRSE.

If you want to use the local accounts instead of SSO, manually go to the following URLs:

• Registration: http://localhost:8000/register/
• Login: http://localhost:8000/auth/login/

If you use SSO and you already have a local account with the same email address, typically your own, then that account will be updated with the details from the SSO account. So, if you created a superuser account as above with your email and then connect via SSO, then your account will be the superuser account.

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/

Documentation

The documentation is built using the Material theme for MkDocs and can be found at https://imperialcollegelondon.github.io/proCAT/.

Updating Dependencies

You can check all the options for managing dependencies with uv, but a summary would be:

1. To add a dependency use uv add dependency_name.
2. You can add it to a group, as well with the --group flag, eg. uv add --group dev dependency_name.
3. To remove a dependency use uv remove dependency_name.

To upgrade pinned versions, use uv lock --upgrade.

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"

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Diego Alonso Álvarez 💻 🤔 🚇 🚧 👀 ⚠️	Steph Wills 💻 👀 ⚠️	Sahil Raja 💻 👀 ⚠️	Saranjeet Kaur 💻 👀 ⚠️	jfcoker 💻 👀 ⚠️	Adrian D'Alessandro 🤔 🚇	Alexander Nies 💻
laura-ellington 💻	Yash Jani 💻	Tosinibikunle 💻	mjademitchell 💻	Max Gamill 💻

This project follows the all-contributors specification. Contributions of any kind welcome!