Marauder’s Map Backend
Backend for the Marauder's Map Project
💻️ Development
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.
make
📄 A note on 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.
✨ Initial setup
You can quickly set up a dev environment with
make init
Alternatively, do the following:
-
Install Poetry for Python package management.
curl -sSL https://install.python-poetry.org | python3 -
see Poetry docs for alternative installation methods
-
(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
-
Install project dependencies
poetry install
if Poetry starts complaining about
psycopg2-binary
, simply runpip install
manually inside the virtual environmentpoetry run pip install psycopg2-binary==2.9.3
-
Install
pre-commit
hookspoetry run pre-commit install
ensures proper formatting and spots common code bugs when committing code
🐚 Virtual environment
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.
Integration with VS Code
If you're using VS Code, and did not set virtualenvs.in-project=true
above, you should tell VS Code where your Poetry virtual
environment is located
Run
make vscode
or perform the following steps:
Open Workspace Settings (JSON)
via the command palette (Ctrl+Shift+P
). This will open.vscode/settings.json
.- Add the following settings
{
"python.pythonPath": "<Poetry Virtualenv Path>",
"python.defaultInterpreterPath": "<Poetry Virtualenv Executable>"
}
where <Poetry Virtualenv Path>
and <Poetry Virtualenv Executable>
need to be replaced with your Poetry env values. These can be found with the following command
poetry env info
This will display something like
...
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
...
- Back in your Workspace Settings, replace
<Poetry Virtualenv Path>
with the value ofPath
and<Poetry Virtualenv Executable>
with the value ofExecutable
. For the above example, it will look like this
{
"python.pythonPath": "/home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10",
"python.defaultInterpreterPath": "/home/<user>/.cache/pypoetry/virtualenvs/maraudersmap-ljAqK4qE-py3.10/bin/python"
}
🔡 Environment variables
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
🗄️ Start database
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...)
🚀 Run backend
-
Verify that the connection string inside
.env
points to your running database -
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 outsidelocalhost
⏩️ Database Migrations
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.
Create migrations
make sure the database is running
Migration files can be autogenerated with the following
cd maraudersmap
alembic revision --autogenerate -m "<Some descriptive title>"
Apply migrations
make sure the database is running
A database can be upgraded to the latest version with the following
cd maraudersmap
alembic upgrade head
🌱 Seed database
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.
seed.sql
Update 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
💣️ Delete database
The database can be deleted with
make nukedb
or
docker stop maraudersmap-pg
docker rm maraudersmap-pg
docker volume rm maraudersmap-data
🌐 Deployment (with Fly.io)
The backend can be deployed in a lot of places. We currently use Fly.io for quick prototyping.