Lokalny setup backendu

Disclaimer

Poniższa instrukcja jest przeznaczona dla zespołu frontendowego Eventownika.

W przypadku jakichkolwiek problemów z backendem, przez które zdeployowana wersja może być czasowo niedostępna lub niestabilna, warto znać sposób uruchomienia całego stacku backendowego lokalnie. Dotyczy to zarówno Adonisowego (wkrótce Nestowego) backendu, jak i Postgresa.

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 zkonteneryzowanego Postgresa. Jeśli nie wiesz czym jest Docker, najlepiej na początku zapoznaj się z dokumentacją.

Postgres

Zanim zainstalujemy backend, musimy najpierw zainstalować 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:

   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.

   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:

   docker ps

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

   Bardzo ważne

   Upewnij się, że w kolumnie PORT w wierszu dla naszego kontenera jest napisane 0.0.0.0:5432->5432/tcp. Jeżeli napisane jest jedynie 5432, to kontener nie jest dostępny dla zewnętrznych połączeń - w naszym przypadku zewnętrznym połączeniem będzie backend, który w takiej sytuacji nie będzie mógł się połączyć z bazą. Wówczas, może być to spowodowane włączeniem kontenera z poziomu interfejsu Docker Desktop - jeśli tak zrobiłeś/aś, wyłącz kontener w panelu i włącz go komendą wskazaną w kroku 3.

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.

Etap opcjonalny

Instalacja pgAdmin nie jest wymagana aby wszystko działało, ale instalacja jest zalecana - zawsze może się przydać.

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

Aktualnie wciąż korzystamy z wersji v2 backendu, która stoi na frameworku AdonisJS. W niedalekiej przyszłości będziemy przejść na wersję v3, która stoi na frameworku NestJS.

Instalacja

1. Sklonuj repozytorium backendu.

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

2. Zainstaluj paczki.

   npm install

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

   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

   hCaptcha

   Wskazane wartości HCAPTCHA_SECRET i HCAPTCHA_SITEKEY są testowymi wartościami podanymi w dokumentacji hCaptcha. Są to właściwe wartości dla celów developmentowych, ponieważ dzięki nim captcha przepuszcza automatycznie i nie trzeba przy każdym logowaniu czy rejestracji na wydarzenie rozwiązywać puzzli.

   SMTP

   Ta instrukcja nie obejmuje lokalnej konfiguracji SMTP - wobec tego, na lokalnym setupie nie będzie działać wysyłanie maili. Skontaktuj się z zespołem (preferowalnie techleadem backendu) w celu uzyskania danych.

   Sprawdź kluczowe zmienne

   W kontekście Dockera, wartość localhost i 127.0.0.1 NIE JEST tym samym. Aby uniknąć potencjalnych błędów związanych z IPv4 i IPv6, dla zmiennej DB_HOST zawsze korzystaj z explicite adresu 127.0.0.1.

   Ponadto, upewnij się, że zmienne DB_HOST, DB_PORT, DB_USER, DB_PASSWORD i DB_DATABASE są ustawione na wartości zgadzające się z tymi ustawionymi przy odpalaniu kontenera Postgresa (krok 3. w sekcji Postgres).

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

   node ace migration:run

5. Zseeduj bazę danych (po frontasiowemu: wypełnij ją jakimiś danymi). Na dzień 23.12.25 backend ma tylko jeden seeder, wobec czego w naszym przypadku wykonanie poniższej komendy doda do tabeli permissions w bazie kluczowe informacje na temat uprawnień organizatorów wydarzeń.

   node ace db:seed

6. Uruchom serwer

   npm run dev

To wszystko jeśli chodzi o lokalny setup wszystkiego co związane z backendem. Teraz należy upewnić się, czy wszystko mamy dobrze skonfigurowane po froncie.

Dalsze użytkowanie

Przed każdym uruchomieniem backendu:

• Zaktualizuj kod o najnowsze zmiany z Githuba,
• Upewnij się, że wszystkie paczki są zainstalowane,
• Wykonaj migracje.

# 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:

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

Ważne

• Upewnij się, że NEXT_PUBLIC_HCAPTCHA_SITEKEY jest taki sam co HCAPTCHA_SITEKEY na backendzie,
• NEXT_PUBLIC_EVENTOWNIK_API MUSI mieć dopisane /api/v1 na końcu,
• Z kolei NEXT_PUBLIC_PHOTO_URL NIE MA dopisanego /api/v1.

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 pojawią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