Club Portal Backend

Table of Contents

• Getting Started
  • Prerequisites
  • Quick Start
  • Running the Server
• Admin Dashboard
• Usage
  • REST API
• Server "Modes"
• Taskfile Commands
• Local Dev Links
• Contributing
  • Pull Requests

Getting Started

Prerequisites

• Docker, Docker Compose: https://docs.docker.com/desktop/
• Python: https://www.python.org/downloads/
• VSCode: https://code.visualstudio.com/download
• UV: https://docs.astral.sh/uv/getting-started/installation/

Optional:

• Taskfile for managing commands and local tasks: https://taskfile.dev/installation/
• Anaconda for managing Python virtual environments: https://www.anaconda.com/download

Quick Start

If you have docker installed, run these commands:

# Pull the repo from github
git clone https://github.com/UF-CSU/club-portal-backend.git
cd ./club-portal-backend

# Copy env variables
cp sample.env .env

# Sync packages for local dev
uv sync --no-group prod

# Start docker compose
docker-compose --profile dev up --build

Running the Server

With TaskFile

If you have Taskfile installed, you can just run:

task dev

This will build the docker containers and spin up the dev servers.

You can add mock data (located in app/fixtures/) with this command:

task loaddata

And you can run unit tests with:

task test

If you make changes to the database, make sure to create a migration file and apply that migration file to the database:

task makemigrations
task migrate

Finally, to stop all docker container and clear the database:

task clean

To clear all cache:

task cache_clear

To clear cache with a certain prefix (ex: "club-previews"):

task cache_clear -- club-previews

Without Taskfile

You can manually start up the docker containers with the following commands:

# Setup env variables and build docker images
cp sample.env .env
docker-compose --profile dev build

After building the docker image, you can run this to start the servers:

docker-compose --profile dev up

To load mock data:

docker-compose run --rm app sh -c "python manage.py loaddata fixtures/*"

To make migration files and apply them to the database:

docker-compose run --rm app sh -c "python manage.py makemigrations"
docker-compose run --rm app sh -c "python manage.py migrate"

To run unit tests:

docker-compose run --rm app sh -c "python manage.py test"

And finally, to clean up all the docker containers and clear the database:

docker-compose --profile dev down --remove-orphans -v

Admin Dashboard

You can log into the admin dashboard by going to the route /admin and using the following credentials:

• Username: admin@example.com
• Password: changeme

These defaults are set via environment variables:

DJANGO_SUPERUSER_EMAIL="admin@example.com"
DJANGO_SUPERUSER_PASS="changeme"

If you want to change these values, copy the sample.env file to a new .env file and change the values. If you already created an admin with the other credentials, then another one won't be created automatically. To get another one to be created automatically, remove the database and restart the app with this command:

docker-compose down --remove-orphans -v
docker-compose up

If you want to create a new admin without removing the old database, run this command:

docker-compose run --rm app sh -c "python manage.py createsuperuser --no-input"

Usage

For more detailed info, look at the docs in docs/pages/, or visit http://localhost:8001/ if you have the server running.

REST API

1. Go to http://localhost:8000/api/v1/docs/#/user/user_token_create
2. Use admin@example.com as the username and changeme as the password (unless you have overridden it) and submit a POST request to the user token route.
3. Use this token to access the rest of the api.

Server "Modes"

You can run the project in multiple different environments, which are referred to as "modes".

Mode	Purpose
Dev	Main development mode, uses mock data in leu of making requests to microservices
Network	Does not use mock data, connects to any needed microservices
Test	Slimmer version of dev mode for unit testing
Production	When the project is run in a cloud environment and receiving traffic

Taskfile Commands

If you have Taskfile installed, you can use the following:

Command	Purpose
task setup	Setup local python environment
task dev	Start the server in "dev" mode
task dev:slim	Start only essential dev services
task network	Starts the server in "network" mode
task test	Run unit tests
task test -- app_name	Run unit tests for a specific app (replace "app_name")
task makemigrations	Create database migration files
task makemigrations:dry-run	Test makemigrations output and don't create files
task migrate	Apply migration files to the database
task lint	Check code lint rules with Flake8
task format	Check but don't apply formatting rules
task format:fix	Format codebase using Black
task shell	Start a new Django interactive shell
task shell:redis	Starts a new interactive redis shell using redis-cli
task shell:db	Starts a new interactive postgres shell using Django's dbshell
task show_urls	Show all available urls for the server, and their reverse labels
task loaddata	Load all available fixtures/mock data into database
task generate_types	Create TypeScript interfaces for serializers
task cache_clear	Clear all cached data
task cache_clear -- cache_prefix	Clear cache with prefix (replace "cache_prefix")
task cache_keys	List all keys in cache
task cache_keys -- cache_prefix	List all keys matching prefix (replace "cache_prefix")
task down	Stop all docker containers created by task dev
task clean	Stop containers and remove volumes created by task dev
task down:slim	Stop all docker containers created by task dev:slim
task clean:slim	Stop containers and remove volumes created by task dev:slim

Local Dev Links

Running the server in dev mode will start up the following services:

Service	Description	Link
Django Server	Main development server	http://localhost:8000/
API Docs	REST API documentation created by Swagger/OpenAPI	http://localhost:8000/api/docs/
OAuth API Docs	OAuth REST API documentation created by django-allauth	http://localhost:8000/api/oauth/openapi.html
Admin Dashboard	Django's model admin dashboard	http://localhost:8000/admin/
Documentation Site	Browseable documentation site for the project	http://localhost:8001/
Test Coverage	A detailed view of test coverage	http://localhost:8002/
PGAdmin	Directly view and manage postgres database for debugging	http://localhost:8888/
MailHog	Local test email server to view emails sent by django	http://localhost:8025/

All of these servers are started up with the "dev" profile in docker compose, if you want to run only essential services you can run:

task dev:slim

Or, without taskfile:

docker-compose --profile slim build
docker-compose --profile slim up

Contributing

To contribute to the project, you can work on any issues not claimed by anyone. Any unassigned issue is fair-game, so make sure to comment on an issue you want to work on so it can be assigned to you.

It is recommended to open smaller pull requests (PRs) that have completed features, compared to larger PRs with a set of different/similar features. This is to reduce merge conflicts and make sure everyone has the updated code.

For more information about contributing, view CONTRIBUTING.md.

Pull Requests

When submitting a pull request (PR), it will be rejected if the unit tests fail. It is recommended to format your code before making a PR, but it's not required (code can still be merged into main if it fails the linting tests).

To run unit tests:

task test

Check linting:

task lint

Format code:

task format:fix