Helium Platform

The backend platform for Helium, which includes both API and worker functionality. Docs for integrating with the API can be found here.

Released container images are published to Helium's AWS ECR.

Prerequisites

• Docker
• Python (>= 3.12)
• MySQL (>= 8)
• Redis (>= 5)

Getting Started

The platform is developed using Python and Django.

This project is configured to work with a Virtualenv within a Docker container. Once provisioned, development can be done offline, as the container built for development includes LocalStack to emulate AWS services locally.

Development

Docker Setup

To provision the Docker container with the Python/Django platform build and all dependencies, execute:

make

This builds and starts two containers, one for the API (named platform-api-1), and one for the Worker (named platform-worker-1). Once running, the platform API is available at http://localhost:8000, and the platform Worker is running to execute async and scheduled tasks.

To create an admin user, you can run:

docker exec -it platform-api-1 python manage.py createsuperuser

An admin extends a basic user (when you register from the frontend website) with access to the admin site.

The shell of containers can be accessed using their name, like:

docker exec -it platform-api-1 /bin/bash

Image Architecture

By default, the Docker image will be built for linux/arm64. To build a native image on an x86 architecture instead, set PLATFORM=amd64.

Project Information

The platform is split up into several modules, all contained within this repository. The base configuration is defined under conf. The applications within this project are:

• auth
• common
• feed
• importexport
• planner

There are also some special environment variables that can be set in development or deployment of the project:

• ENVIRONMENT
  • dev-local provisions hosts as localhost
  • local provisions hosts as localhost for use outside of Docker (ex. when using Django's runserver command)
  • prod provisions hosts to be suffixed with heliumedu.com
  • Any other env name provisions a prod-like hostname with <ENVIRONMENT>. as the prefix
• PLATFORM_BEAT_MODE
  • Set to True to start a Beat scheduler (only one should ever be running in the fleet) instead of a Worker when launching from Celery
• USE_AWS_SECRETS_MANAGER
  • Set to True to use AWS Secrets Manager before falling back to environment variables
• USE_NGROK
  • Set to True to have pyngrok open a ngrok tunnel and provide a real hostname (only works when ENVIRONMENT is not prod

These and other environment variables can be configured in the .env file. This is also where credentials to third-party services (for example, AWS services like SES) can be set. Do NOT commit real credentials to third-party services, even in example files.

Before commits are made, be sure to run tests and check the generated coverage report.

make test

Frontend

The frontend is served from a separate repository and can be found here. Using Docker, the frontend and platform containers can be started alongside each other to almost entirely emulate a prod-like environment locally using the deploy project. For functionality that still requires Internet-connected external services (ex. emails and text messages), provision the dev-local Terraform Workspace, which is meant to work alongside local Docker development.

Note that the frontend was previously bundled, rendered, and served as a part of this project, but it was pulled out into its own project with the with 1.4.0 release. For reference, checkout the 1.3.8 tag or download it here to see how this was previously done.

Documentation

Auto-generated API documentation is accessible via any environment at /docs. Additional documentation can be found on the Platform Wiki.