Compass Interface — the unofficial Compass API

The Compass Interface project aims to provide a unified and well-documented API to the Scouts' national membership system, Compass.

Notice

This is not an official API to Compass and as such should be used in a way that doesn't cause a high request load on the Compass system.

Please also remember your personal data handling obligations (under both GDPR and Scouting policies) whilst using this system.

Objectives

The project aims to:

• increase flexibility and simplicity when developing applications that interface with Compass data,
• provide stability and abstract complexities of Compass, and
• enable greater support to our adult volunteers and members.

Where to get it

The source code for the project is hosted on GitHub at the-scouts/compass-interface

The project can be installed through either pip or conda.

# conda
conda env create
conda activate compass-interface

If installing dependencies from PyPI, please strongly consider using a virtual environment to isolate your packages.

# or PyPI
pip install -r requirements.txt 

Dependencies

• compass - Core Compass Interface, with parsing and validation logic
• pandas - for data management and transformation
• numba - to speed things up
• pyarrow - to process and move data fast
• FastAPI - for an intuitive API
• uvicorn - serving on the lightning-fast ASGI server

Dev-dependencies

We use black, isort, ipython and others to speed up the development process!

Licence

Compass Interface is naturally open source and is licensed under the MIT license.

Usage

Running the API

To run the API either run uvicorn compass.api.app:app --reload in the root directory, or run the app.py file in the /compass/api/ directory. This second method also enables interactive debugging.

Alternativley, use Docker

Running the Compass Interface files directly

To run the Compass Interface files directly the top-level script.py file is useful for getting started immediately. Please make sure not to commit credentials to git, as these are assumed public as soon as they are on GitHub.

Docker

To start docker compose, run docker-compose up -d.
To stop docker, run docker-compose down.
To rebuild the app, run docker-compose build --no-cache backend.
To access an interative shell, run docker run -it backend bash.

When the containers are running, Redis Insight is available at localhost:8001, the FastAPI app is reached at localhost:8888, and the Traefik reverse proxy is localhost:80 for the app proxy and localhost:8080 for Traefik's dashboard.

Support

For support please contact Adam Turner (@AA-Turner). There is a wider community of interest on the UK Scouts IT Lab group.

Ideas, Bugs, Features

Please use GitHub issues / Pull Requests to note bugs or feature requests.