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 update
conda activate compass-interface

If installing dependencies with pip, use a virtual environment to isolate your packages.

# or PyPI

# create venv
python -m venv venv

# activate venv - windows
.\venv\Scripts\activate
# activate venv - unix-like (macOS, linux)
source env/bin/activate 

# install dependencies
python -m 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.

Alternatively, 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 run Compass Interface locally, we provide docker templates in /docker.

! Note: All commands below are run in the /docker directory.

Local hosting / development

To start docker, run docker compose -f docker-compose.yml up -d.
To rebuild the Compass Interface backend, run docker buildx build -t scouts/compass-interface-backend --load -f backend.dockerfile ..
To stop docker, run docker compose down.
To remove old build files, run docker container prune -f; docker image prune -f

Deployment

To start docker, run docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d.
To stop docker, run docker-compose down.

Ports

When the containers are running, the FastAPI app is reached at localhost:8888.

If you are running the deployment configuration, you will also find the Traefik reverse proxy at localhost:80 and Traefik's dashboard at localhost:8080.

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.