backend.d sektionen.se

Backendprojektet hanterar D-sektionens data och erbjuder en API för de andra projekten på sektionen att interagera med, främst medlemstjänsten.

Projektet är byggt med Python och ramverket Django. I en utvecklingsmiljö används en lokal SQLite-databas medan i produktion används en Postgres-databas.

Utveckling

Förutsättningar

Python 3.12 eller nyare krävs för att köra projektet. För att checka din Python-version kan du köra följande:

python3 --version

[!NOTE] Wikin och projektet i allmänt tar för givet en viss bekantskap med Python och Django samt Django REST-framework. Det kan vara en bra idé att bekanta sig med dessa teknologier innan du dyker in i kodbasen. Användbara länkar finns i botten av denna artikel.

Snabbstart

[!NOTE] Det rekommenderade sättet att köra projektet är genom Docker. Om du dock av någon anledning skulle behöva gå runt Docker finns det instruktioner längre ner i den här artikeln.

Miljövariabler

Sakta i backarna! Några miljövariabler krävs innan du kan starta projektet:

Döp om eller kopiera .env.sample till .env:

cp .env.sample .env

..och öppna den nya filen i en texteditor.

De följande variablerna måste vara satta:

CLIENT_ID=
CLIENT_SECRET=
LIU_TENANT_ID=

Dessa värden skapas av LiU och ska inte läckas. Du får tillgång till dem från din Webmaster eller någon annan i WebbU.

För att enkelt kunna logga in på adminpanelen senare är det dessutom en bra idé att sätta SUPERUSER_USERNAME och SUPERUSER_EMAIL innan du startar servern första gången.

SUPERUSER_USERNAME=liuid123
SUPERUSER_EMAIL=liuid123@student.liu.se

Genom att sätta dessa skapas ett superuser-konto som du kan komma åt genom att logga in med ditt LiU ID. Det går dock inte att logga in i detta kontot med hjälp av lösenord, för att tillåta det krävs att du skapar kontot manuellt.

Starta servern

Projektet använder Docker Compose för att spinna upp databasen och själva Django-projektet, samt några andra småtjänster. Efter att du satt variablerna i .env filen, kör följande:

docker compose up

[!TIP] Ifall du använder MacOS, kolla in https://stackoverflow.com/a/53310545/9966843

Servern ska nu köras på http://127.0.0.1:8000. Om du navigerar till URL:en ska den kasta en 404-error och visa en lista på tillgängliga API-rutter om allt fungerar som det ska. Om detta inte händer har någonting gått snett.

Compose fortsätter köra även om du stänger ditt terminalfönster, så för att dra ner alltihopa kan du använda:

docker compose down

Om du dessutom vill rensa all data (volymer), lägg till -v flaggan:

docker compose down -v

Migrationer

Köra migrationer

Databasmigrationer kan köras med:

docker compose exec backend python manage.py migrate

docker compose exec används för att köra kommandon innuti den körande Docker-containern.

Detta kommer att migrera tabellerna (modellerna) i databasen till deras senaste versioner, eller skapa en ny databas om den inte finns än.

Migrationer körs automatiskt när containern startas, så du behöver sällan köra kommandot manuellt.

Skapa migrationer

Efter att du gjort ändringar i modellerna krävs det att du skapar en migration för att uppdatera databasen. Django kan automatiskt generera dessa genom att du kör följande:

docker compose exec backend python manage.py makemigrations

Du kan sedan applicera migrationen genom att köra kommandot från det tidigare kapitlet, eller genom att starta om servern.

Adminpanelen

Django har en inbyggd adminpanel där man kan inspektera och redigera databasen. Panelen används i produktion av exempelvis Werk för att hantera de bokningsbara föremålen, men är även mycket användbar under utveckling.

Adminpanelen ligger på http://localhost:8000/admin och kräver inloggning.

Inloggning med LiU ID

Om du följde "Snabbstart"-guiden och satt ditt LiU ID i miljövariablerna kan du använda en lokal instans av medlemssidans frontend för att enkelt logga in med hjälp av ditt LiU ID.

Instruktioner för att sätta upp medlemssidan finns på wikisidan. Logga helt enkelt in där och navigera tillbaka till adminpanelen. Efter det borde du ha tillgång och bli inloggad automatiskt.

Inloggning med lösenord

Docker Compose-filen är i nuläget inte uppsatt för att skapa superuser-användare med lösenord. Detta innebär att du måste skapa ett konto för dig själv manuellt innan du kan logga in. Kör följande:

docker compose exec backend python manage.py createsuperuser

Django kommer fråga dig om diverse uppgifter. Samtliga fält kan lämnas blanka förutom ditt lösenord. Om inget användarnamn sätts det automatiskt sättas till "root".

Lokal utvecklingsmiljö utan Docker

Om du mot all förmödan inte kan/vill köra Docker går det att sätta upp en miljö lokalt.

Skapa och aktivera virtuella Python-miljön

Linux/MacOS

python3 -m venv .venv
source .venv/bin/activate

Windows

Öppna Powershell som administratör. Följande kommando behöver bara köras en gång per maskin:

set-executionpolicy remotesigned

Kör sedan:

python -m venv .venv
.venv/Scripts/activate

Installera dependencies

Installera sedan dependencies för projektet:

pip install -r requirements.development.txt

Ett valfritt men rekommenderat steg är att sätta upp pre-commit hooks. Dessa körs innan varje git commit och säkerställer att du alltid checkar in kod som är formatterad:

pre-commit install

Starta servern

Starta till sist servern med det följande kommandot:

python manage.py runserver

Tidigare i guiden finns kommandon som börjar med docker compose exec. När du ska hantera migrationer och liknande i en miljö utan Docker ska du givetvis inte köra kommandon på det sättet, utan kör istället python direkt.

System

Bokning

Bokningssytemet hanterar bokningar av D-sektionens resurser såsom bilar, utrustning och förrådsutrymme.

Själva uthyrningsprocessen och administreringen sköts av utskottet WerkMästeriet och inte WebbU själva.

Föremålspooler

En grupp av bokningsbara föremål definieras av en ItemPool. Varje ItemPool kan ha ett godtyckligt antal ItemPoolItems, som representerar de individuella föremålen. De flesta pooler har bara ett föremål; exempelvis har poolen Släp endast ett föremål: Släp. En pool kan också tillhöra en kategori tillsammans med andra pooler.

Listan över kategorier och bokingspooler som från medlem.d-sektionen.se.

En pool har dessutom ett antal andra fält:

• terms: ett textdokument med villkor som gäller när man bokar föremål ur poolen. Dessa visas på medlemssidan precis bredvid "Boka"-knappen.
• always_requires_confirmation: om satt till true krävs det alltid att bokningar bekräftas manuellt av Werk. Läs mer i avsnittet "Bekräftelse" nedan.
• min_booking_hours: det minsta antalet timmar som ett föremål kan bokas.
• min_booking_hours_restricted: det minsta antalet timmar som ett föremål kan bokas som en begränsad tidsperiod. Läs mer nedan.
• auto_confirm_max_booking_hours: det maximala antalet timmar som ett föremål kan bokas utan att kräva manuell bekräftelse. Läs mer nedan.
• webhook: en Slack eller Discord webhook som kallas när en bokning som kräver manuell bekräftelse skapas eller uppdateras.

Tillbehör

Förutom bokningsbara ItemPoolItems kan varje ItemPool även innehålla ett antal ItemPoolAccessorys. Dessa representerar tillbehör som är nödvändiga för att använda det bokningsbara föremålet och bokas alltid i samma mängd som ursprungsföremålet. Till exempel kräver fulvinstunnor ett lika antal fulvinslock bokas.

Varje tillbehör definerar en lista på föremål de är kompatibla med. Föremål och tillbehör som är inkompatibla med varandra går inte att boka tillsammans. I fulvinstunnornas fall har fulvinslocken och tunnorna varierande storlek, där locken endast är kompatibla med tunnor av samma storlek.

Begränsade bokningsperioder

En begränsad bokningsperiod är en speciell typ av bokning. Under en begränsad bokningsperiod måste alla bokningar av föremålet manuellt bekräftas. Exempel under året när dessa brukar användas är av STABEN under Nolle-P och Link under Linkdagarna.

Bekräftelse

När en bokning skapas händer en av två saker:

• Bokningen bekräftas automatiskt och är direkt giltig.
  • Systemet gör sitt bästa för att välja kompatibla föremål/tillbehöver som är tillgängliga under hela bokningsperioden och tilldelar dessa till bokningen.
  • Om detta inte är möjligt misslyckas bokningen och ett felmeddelande returneras.
• Bokningen kräver manuell bekräftelse av Werk.
  • Om en Webhhook är definierad på poolen skickas ett meddelande till den webhooken med information om bokningen.
  • När bokningen ska bekräftas kan Werk antingen välja föremål/tillbehör manuellt, eller låta systemet lösa tilldelningen automatiskt.

Bokningen kräver manuell bekräftelse om någon av de följande villkoren är uppfyllda:

• Bokningen är en begränsad bokningsperiod.
• Poolen har always_requires_confirmation satt till true.
• Bokningen är längre än poolens auto_confirm_max_booking_hours.
• Bokningen överlappar med en bokningsbekräftad period.

Fler resurser

För att lära dig mer om teknologierna som används i projektet kan du ta del av följande länkar:

• docs.djangoproject.com
• www.django-rest-framework.org
• docs.docker.com