Backend for the Marauder's Map Project

This project assumes a Python version of ^3.10, and has not been tested with any other versions. See Python docs for installation instructions for your system.

The following setup references some commands that utilize the make build tool (available in Unix). These are optional convenience commands that might not fit all systems or use cases. Have a look inside Makefile to see what they do. Alternatives are provided for each make command.

You can quickly set up a dev environment with

make init

Alternatively, do the following:

1. Install Poetry for Python package management.

   curl -sSL https://install.python-poetry.org | python3 -
   

   see Poetry docs for alternative installation methods

2. (Optional, but recommended)

   Tell Poetry to create the virtual environment inside the project directory

   poetry config --local virtualenvs.in-project true
   

   this makes it easier for development environments like VS Code to recognize the correct Python intepreter for the project

3. Install project dependencies

   poetry install
   

   if Poetry starts complaining about psycopg2-binary, simply run pip install manually inside the virtual environment

   poetry run pip install psycopg2-binary==2.9.3
   

4. Install pre-commit hooks

   poetry run pre-commit install
   

   ensures proper formatting and spots common code bugs when committing code

Most commands need to be run from inside the Poetry virtual environment. This is done by first entering the environment shell with

poetry shell

if the above command fails, try the following instead

source $(poetry env info --path)/bin/activate

Alternatively: prepend all commands with poetry run to run them from inside the virtual environment.

make vscode

{
    "python.pythonPath": "<Poetry Virtualenv Path>",
    "python.defaultInterpreterPath": "<Poetry Virtualenv Executable>"
}

poetry env info

...

Virtualenv
Python:         3.10.4
Implementation: CPython
Path:           /home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10
Executable:     /home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10/bin/python
Valid:          True

...

{
    "python.pythonPath": "/home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10",
    "python.defaultInterpreterPath": "/home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10/bin/python"
}

A template .env.template file is included inside /maraudersmap, which can be copied to a local, gitignored .env file. These values are only used for local development (e.g. a local database connection string).

cp maraudersmap/.env.template maraudersmap/.env

The project requires a PostgreSQL database. A quick approach for setting this up is to run the official Docker image. Just make sure you have installed Docker first.

A make command is available to initialize and start a database with Docker

make db

this command also applies new migrations

Alternatively, run the following

docker run -p 5432:5432 -e POSTGRES_PASSWORD=password -v maraudersmap-data:/var/lib/postgresql/data --name maraudersmap-pg postgres:14.5

you could choose any password for the database, but make sure to update the connection string accordingly

the above command creates a named volume maraudersmap-data, which will persist the database data between image restarts (see Delete database if you need a fresh start...)

1. Verify that the connection string inside .env points to your running database

2. Apply any new database migrations

3. Start server with

   make api
   

   or

   cd maraudersmap
   uvicorn main:app --host 0.0.0.0 --reload

   must be run from /maraudersmap directory to recognize .env

   using --host 0.0.0.0 seems to be required for accessing the backend from outside localhost

Any changes to the database schema need to be documented in an Alembic migration file (maraudersmap/alembic/versions), which is used to upgrade tables in existing databases.

make sure the database is running

Migration files can be autogenerated with the following

cd maraudersmap 
alembic revision --autogenerate -m "<Some descriptive title>"

make sure the database is running

A database can be upgraded to the latest version with the following

cd maraudersmap 
alembic upgrade head

make sure the database is running

Your database can be kickstarted by injecting some sample code provided in seed.sql

make seed

or

docker exec -i maraudersmap-pg /bin/bash -c "PGPASSWORD=password psql --username postgres postgres" < maraudersmap/database/seed.sql

assumes names and passwords as given in docker run above.

If you want to update the sample data, simply replace the file with a dump of your current database

make dump

or

docker exec -i maraudersmap-pg /bin/bash -c "PGPASSWORD=password pg_dump --username postgres postgres" > maraudersmap/database/seed.sql

The database can be deleted with

make nukedb

or

docker stop maraudersmap-pg
docker rm maraudersmap-pg
docker volume rm maraudersmap-data

The backend can be deployed in a lot of places. We currently use Fly.io for quick prototyping.

See FLY_DEPLOYMENT.md