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. Clone this repository:

bash git clone https://github.com/ImperialCollegeLondon/proCAT.git

1. Move into the created repo.

bash cd proCAT

1. Create and activate a virtual environment. This creates a .venv in the same directory with the environment, including the dev dependencies:

bash uv sync

1. (Optionally) install tools for building documentation:

bash uv sync --group doc

1. Install the git hooks:

bash pre-commit install

1. Run the web app:

bash 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:

bash python manage.py migrate

then restart it.

1. Run the tests:

bash pytest

1. Create an admin account to access admin backend:

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

Running with Docker

Ensure you have Docker installed. The docker-compose.yml file supports two modes selected via Compose profiles.

All the environment variables used by the app (Clockify, OIDC/SSO, and the production-only settings) are documented in .env.example, which indicates which ones are mandatory for each mode. Copy it to .env and fill in the values you need; Docker Compose picks it up automatically.

NOTE: The database used when running in Docker is stored in a named volume (db) and is preserved across container restarts. This database is different from the one used when running the web app directly on the host, as described above. Content added to the database in the docker-based deployment (either of the two modes) will not be available when using the local deployment and vice-versa, neither migrations.

Development mode (default)

Use this for day-to-day feature work. It mounts the source tree into the container so any file change is picked up immediately by Django's auto-reloader — no rebuild needed. Django's built-in development server is used with DEBUG=True, which gives detailed error pages and serves static files automatically without a collectstatic step.

docker compose up

The app is available at http://localhost:8000. If it is the first time you run it, or after deleting the local database, you will need to create a superuser account:

docker compose exec app python manage.py createsuperuser

Rebuilding the image is only necessary when dependencies change (i.e. pyproject.toml or uv.lock are modified):

docker compose up --build

Production-like mode

Use this to test behaviour that only surfaces outside of DEBUG=True: production settings, static files served via WhiteNoise from a pre-collected staticfiles/ directory baked into the image, gunicorn as the WSGI server, and a Caddy reverse proxy in front of it. The source tree is not mounted, so the image must be rebuilt after any code change.

This mode requires a SECRET_KEY environment variable:

export SECRET_KEY="a-long-random-secret"
docker compose --profile production up web proxy

The app is available at http://localhost. Naming the services (web proxy) explicitly prevents the development app service from starting alongside them.

After code changes, rebuild before restarting:

docker compose --profile production up --build web proxy

Stopping services

For development mode:

docker compose down

For production-like mode the profile must be specified so Compose includes the web and proxy services:

docker compose --profile production down

The database is stored in a named Docker volume (db) and is preserved across restarts. To also delete the database, add --volumes to either command.

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 💻	Sandra AC 💻 🐛 ⚠️

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