Przejdź do głównej zawartości
Solvro

Lokalny setup backendu

Aktualnie dostępne są dwie wersje backendu:

  • v2 - oparty na frameworku AdonisJS, aktualnie wdrożony na produkcji.
  • v3 - oparty na frameworku NestJS, nowa wersja w trakcie wdrażania.

Instrukcja poniżej obejmuje setup obu wersji. W zależności od potrzeb, przełączaj się między zakładkami v2 i v3.

Wymagania

Oprócz podstawowych narzędzi, które już na pewno masz jeśli pracujesz nad frontem (Git, NodeJS etc.), dodatkowo potrzebny jest jedynie Docker Desktop. Jest to aplikacja desktopowa do zarządzania kontenerami Docker, przy której instalacji równocześnie zostaną zainstalowane wszystkie inne rzeczy potrzebne by odpalać u siebie kontenery (np. docker engine). Będzie ona potrzebna w celu łatwej, lokalnej instalacji zkonteneryzowanych serwisów. Jeśli nie wiesz czym jest Docker, najlepiej na początku zapoznaj się z dokumentacją.

Docker

Zanim zainstalujemy backend, musimy najpierw uruchomić wymagane serwisy w Dockerze.

Backend v2 wymaga jedynie Postgresa.

Instalacja

  1. Pobierz, zainstaluj i uruchom Docker Desktop.

  2. Pobierz oficjalny obraz Postgresa. W tym przykładzie używamy wersji 17-alpine (zajmuje mniej miejsca niż standardowe) ale możesz wybrać właściwie dowolną wersję. Obraz można pobrać z poziomu interfejsu Docker Desktop lub poniższą komendą w terminalu:

    Okno terminala
    docker pull postgres:17-alpine

  3. Uruchom nowy kontener z obrazem Postgresa

    • Zamiast eventownik-local można wybrać dowolną nazwę kontenera,
    • Flagi -e ustawiają zmienne środowiskowe,
    • Flaga -p ustawia port, na którym działa postgres. 5432 to standardowy port Postgresa. Nie zmieniaj go.
    Okno terminala
    docker run --name eventownik-local -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=root -e POSTGRES_DB=postgres -d postgres:17-alpine

  4. Zweryfikuj działanie kontenera. W terminalu wpisz:

    Okno terminala
    docker ps

    Wynikiem komendy będzie tabela z listą kontenerów.

Dalsze użytkowanie

  • Aby zatrzymać kontener (wyłączyć bazę) wpisz w terminalu docker stop eventownik-local lub kliknij przycisk Stop w Docker Desktop.
  • Aby uruchomić kontener ponownie, kliknij przycisk “Start” w Docker Desktop lub wpisz docker start eventownik-local w terminal - start włącza istniejący kontener, run tworzy nowy!

pgAdmin

Przydatne narzędzie GUI do zarządzania bazą danych, dzięki którym możemy przeglądać zawartość tabeli oraz wykonywać kwerendy. Jeżeli jesteś masochistą, alternatywą jest CLI psql.

Instalacja

  1. Pobierz, zainstaluj i uruchom pgAdmin.
  2. Będąc już na głównym ekranie, kliknij prawym przyciskiem na dropdown “Servers” na sidebarze po lewo opisanym jako “Object Explorer”. Najedź na “Register” i wybierz opcję “Server…”. W ten sposób zarejestrujemy nowy serwer na którym znajduje się baza - w naszym przypadku, serwer działający w kontenerze.
  3. W zakładce “General” okna konfiguracji wpisz dowolną nazwę (Name). Dla wygody zaznacz też “Connect now?” aby automatycznie nawiązać połączenie z bazą po zakończeniu konfiguracji.
  4. W zakładce “Connection” okna konfiguracji wpisz:
    • Host name/address: 127.0.0.1
    • Port: 5432
    • Maintenance database: postgres
    • Username: postgres
    • Password: root
    Dla wygody zaznacz też “Save password?” aby zapisać hasło.

Po zakończeniu instalacji możesz rozwinąć drzewko dla naszej bazy w lewym sidebarze.

Tabele

  1. Nawiguj w drzewku wg.:

    Servers
    └── <Nazwa Bazy>
        └── Databases
            └── postgres
                └── Schemas
                    └── public
                        └── Tables
                            ├── admin_permissions
                            ├── admins
                            ├── adonis_schema
                            └── (...pozostałe tabele)

  2. Zaznacz którąś z tabel.

  3. Na samej górze lewego sidebara opisanego jako “Object Explorer” kliknij w przycisk z ikonką tabeli (tytuł po najechaniu: All Rows).

  4. Na prawo otworzy się nowe okno z kilkoma elementami. Najważniejsza jest znajdująca się na dole tabelka (Data Output), która jest tabelą danych w tej tabeli. Dane możemy intuicyjnie edytować podwójnie klikając na komórki.

Kwerendy

  1. Zaznacz w drzewku bazę danych (“postgres”).
  2. Na samej górze lewego sidebara opisanego jako “Object Explorer” kliknij w pierwszy przycisk z ikonką bazy (tytuł po najechaniu: Query Tool).
  3. Po wpisaniu w okienku kwerendy, odpalamy ją przez F5 lub dedykowany przycisk “Execute Script”.

Backend

Instalacja

  1. Sklonuj repozytorium backendu v2.

    Okno terminala
    git clone https://github.com/Solvro/backend-eventownik-v2.git

  2. Zainstaluj paczki.

    Okno terminala
    npm install

  3. Skonfiguruj zmienne środowiskowe. W folderze projektu stwórz plik .env.local i umieść w nim poniższe zmienne:

    Okno terminala
    TZ=UTC
    PORT=3333
    HOST=localhost
    LOG_LEVEL=info
    APP_KEY=dddddddddddddddddddddddddddddddddddd
    NODE_ENV=development
    DB_HOST=127.0.0.1
    DB_PORT=5432
    DB_USER=postgres
    DB_PASSWORD=root
    DB_DATABASE=postgres
    PHOTO_STORAGE_URL=public/
    TEMP_STORAGE_URL=storage/temp/
    FILE_STORAGE_URL=uploads/
    SMTP_HOST=example.com
    SMTP_PORT=465
    SMTP_USERNAME=abcd@example.com
    SMTP_PASSWORD=12345678
    APP_DOMAIN=https://eventownik.solvro.pl
    SIGNOZ_HOST=http://localhost:4318
    HCAPTCHA_SECRET=0x0000000000000000000000000000000000000000
    HCAPTCHA_SITEKEY=10000000-ffff-ffff-ffff-000000000001

  4. Odpal migracje (po frontasiowemu: skonfiguruj strukturę bazy danych) wpisując w terminalu:

    Okno terminala
    node ace migration:run

  5. Zseeduj bazę danych. Backend v2 ma tylko jeden seeder, dodający do tabeli permissions w bazie kluczowe informacje na temat uprawnień organizatorów wydarzeń. W odróżnieniu od v3, nie dodaje testowych wydarzeń czy kont.

    Okno terminala
    node ace db:seed

  6. Uruchom serwer

    Okno terminala
    npm run dev

Dalsze użytkowanie

Przed każdym uruchomieniem backendu:

  • Zaktualizuj kod o najnowsze zmiany z Githuba,
  • Upewnij się, że wszystkie paczki są zainstalowane,
  • Wykonaj migracje.
Okno terminala
# Aktualizacja
git fetch origin
git pull origin
npm install
node ace migration:run
# Uruchomienie
npm run dev

Dostosowanie frontendu

Pamiętaj aby zmienić plik .env.local w folderze frontendu wg. lokalnego setupu.

Okno terminala
NEXT_PUBLIC_EVENTOWNIK_API=http://localhost:3333/api/v1
SESSION_SECRET=abchjasdhjksadhjkdajkdh
NEXT_PUBLIC_PHOTO_URL=http://localhost:3333
NEXT_PUBLIC_HCAPTCHA_SITEKEY=10000000-ffff-ffff-ffff-000000000001

Troubleshooting

  • Backend Eventownika jest wciąż w stałej rozbudowie - częste zmiany są spodziewane. Jeżeli masz jakiekolwiek problemy, zrób nowy thread na jednym z eventownikowych kanałów na discordzie (#frontend-eventownik lub #backend-eventownik).
  • W trakcie opcjonalnej instalacji pgAdmina, istnieje szansa że stworzył i uruchomił się nowy defaultowy serwer Postgresa. W takiej sytuacji, będzie on kolidował z serwerem z kontenera, ponieważ oba chcą działać na 127.0.0.1 i porcie 5432. Może być to bardzo prawdopodobna przyczyna pojawiających się ewentualnie problemów. W przypadku Windowsa, najprościej będzie wyłączyć go z poziomu menedżera usług:
    • Włącz menedżer usług wyszukując services.msc w menu start
    • W liście usług wyszukaj postgresql-x64-16 - PostgreSQL Server 16 - kliknij prawym przyciskiem myszy i wybierz Właściwości
    • Zatrzymaj usługę i zmień typ uruchomienia na “Wyłączony”, aby nie uruchamiał się automatycznie po starcie komputera