Project READ backend 📚

Django backend for the GSL Hub. Check out the client code here!

Table of contents

• Setup
  • Requirements 📥
  • Running the code 🏃
• Development workflow
  • Accessing the Django admin 🗃
  • Generating seed data 🌱
  • Installing new packages 📦
  • Database migrations 🗃
  • Updating secrets 🔐
  • Testing ✅
    • Run automated tests
    • Manual testing
    • Code Coverage
  • Linting 🧹

Setup

Requirements

• Docker

Running the code

1. Clone this repository and open the project folder:

   git clone https://github.com/uwblueprint/project-read-backend.git
   cd project-read-backend
   

2. Retrieve the environment variables & secrets from the team's Vault (shoutout to the Internal Tools team!).
   1. Follow these docs to get set up with Vault!
      • Skip the section Create a GitHub team – if you haven't been added to the Github team yet, message #project-read-devs on Slack.
      • For the section Configure dev tools for your project repo, setup.sh exists in /scripts, so run ./scripts/setup.sh instead of ./setup.sh.
   2. Pull the secrets into .env:

      vault kv get -format=json kv/project-read | python ./scripts/update_secret_files.py
      

3. Run the Docker container with docker-compose up in the project directory.
   • To run Docker in the background, run docker-compose up -d instead.
   • When you're done, run docker-compose down to stop the containers.
4. Go to localhost:8000! You should see a page that says "Api Root".

Development workflow

Accessing the Django admin

The Django admin provides a content management interface for us to manage our data. This will be helpful for doing manual testing, as you can create test data really easily!

1. Create a superuser under your Blueprint email:

   docker-compose exec web ./manage.py createsuperuser
   

2. Open localhost:8000/admin and sign in.

Generating seed data

This management command will delete all existing records in your database, and populate it with randomly-generated seed data:

docker-compose exec web python manage.py load_initial_data

You can also specify the number of families, sessions, and classes per session to create:

docker-compose exec web python manage.py load_initial_data \
    --families X --sessions X --classes_per_session X

Installing new packages

When adding new Python packages to the project, you'll need to define it as a dependency and rebuild the Docker container.

1. Install the packages and add them to requirements.txt:

   docker-compose exec web pip install [package]
   docker-compose exec web pip freeze > requirements.txt

2. Rebuild the container:

   docker-compose build
   docker-compose up -d

Database migrations

When making changes to a models.py file, you may need to create a database migration so that other machines know to apply your changes. Here are some useful commands!

# Show existing migrations
docker-compose exec web ./manage.py showmigrations

# Make a new migrations file based on your changes to models.py
docker-compose exec web ./manage.py makemigrations

# Apply the migrations to your database
docker-compose exec web ./manage.py migrate

To migrate back to an old version:

docker-compose exec web ./manage.py migrate [app name] [migration name]

# ex. docker-compose exec web ./manage.py migrate accounts 0001_initial

To undo all migrations:

docker-compose exec web ./manage.py migrate [app name] zero

Updating secrets

To pull the latest secrets from Vault:

vault kv get -format=json kv/project-read | python ./scripts/update_secret_files.py

To update our team secrets, see the Vault docs.

Testing

Run automated tests

All automated tests need to pass before code can be merged:

docker-compose exec web ./manage.py test

Manual testing

To test authenticated endpoints locally, you'll need a token from our team's Firebase authentication server. If you don't yet have an account on our Firebase app, message #project-read-devs on Slack to get added!

1. Sync your Firebase user with your Django superuser, and retrieve a token:

   docker-compose exec web ./manage.py sync_firebase_user

   • This token expires after 60 minutes, at which point you should re-run this command to get a new one!
2. You can use this token and pass it as a bearer token for your API requests (using curl, Postman, etc).

Code coverage

A code coverage report tells you how much of the application is being tested. To generate and view a code coverage report:

1. Build and start up the container with docker-compose up --build -d
2. Generate the report with this command.

   docker-compose exec web coverage run --source='.' manage.py test

3. View the report in the terminal with this command

   docker-compose exec web coverage report

4. (Optional) Generate an HTML view with this command.

   docker-compose exec web coverage html

   Then open the file /htmlcov/index.html in your browser.

Lint

docker-compose exec web black .