# Kurierzy

## Wymagania

- **IntelliJ Ultimate** — używamy [Kotlin](<https://kotlinlang.org/>), więc potrzebujemy pełnej wersji IntelliJ;
- **JDK 11** — może być z [https://adoptopenjdk.net/](<https://adoptopenjdk.net/>), choć IntelliJ powinien ją sam pobrać, jeśli nie znajdzie odpowiedniej;
- **PostgreSQL** — powinna zadziałać dowolna aktywna wersja, ale polecamy wyższą niż 10;
- [**Git**](<https://git-scm.com/>);
- [RabbitMQ](<https://www.rabbitmq.com/>) lub Docker.

## TLDR

Zakładając, że możemy używać Docker i IntelliJ, kroki do uruchomienia aplikacji są następujące.

1. Pobieramy projekt z BitBucket.
2. Tworzymy pustą bazę danych.
3. Kopiujemy `application.default.yml` do `application.external.yml` i ustawiamy dostępy do bazy.
4. Kopiujemy `env.default` do `.env` i zmieniamy parametry, jeśli chcemy.
5. Uruchamiamy `docker-compose.yml`.
6. Uruchamiamy aplikację w IntelliJ.

## Pierwsze kroki

### Import projektu

**UWAGA**: BitBucket nie pozwala już na stosowanie haseł. Musimy przygotować *APP password*. Pomóc może instrukcja → [Bitbucket API / App passwords](<https://youtrack.logintegra.com/articles/DEV-A-71/Bitbucket-API---App-passwords>).

Możemy zaimportować projekt bezpośrednio z poziomu IntelliJ — [Check out a project from a remote host](<https://www.jetbrains.com/help/idea/set-up-a-git-repository.html#clone-repo>). W takiej sytuacji powinien on się poprawnie skopiować na dysk i otworzyć w edytorze.

Jeśli jednak byłyby z tym jakieś problemy, możemy projekt sklonować ręcznie. W tym celu przechodzimy na stronę [https://bitbucket.org/logintegraspzoo/microservice-courier/src/master/](<https://bitbucket.org/logintegraspzoo/microservice-courier/src/master/>), wybieramy *Clone* i wklejamy do konsoli.

W IntelliJ natomiast otwieramy go analogicznie do np. Apollo:

1. Uruchamiamy IntelliJ.
2. Wybieramy *Open or Import*, jeśli jesteśmy w okienku wyboru projektu lub *File -\> Open*, jeśli jesteśmy w oknie innego projektu.
3. W okienku wyboru projektu wybieramy z lokalizacji, w której mamy projekt `microservice-courier`, plik `build.gradle.kts` i klikamy *OK*.
4. Pojawi się pytanie, czy chcemy otworzyć plik jako projekt, czy jako pojedynczy plik, klikamy *Open as project*.
5. Po otworzeniu projektu IntelliJ pobierze biblioteki i wykona budowanie w tle, może to chwilę potrwać.
6. Po zbudowaniu projekt jest gotowy do uruchomienia.

### Baza danych

Stwórz bazę danych w PostgreSQL. Zapamiętaj użytkownika i hasło.

### Pliki konfiguracyjne

Skopiuj `/resources/custom-config/application.default.yml` do `resources/custom-config/application.external.yml` i ustaw odpowiednie zmienne, hasła itp.

Ostateczna struktura powinna wyglądać tak:

```
- microservice-courier/
  └─ src/
     └─ main/
        └─ resources/
           └─ custom-config/
              ├─ application.default.yml  // To jest na gicie
              └─ application.external.yml // Tu wprowadzamy zmiany         
```

Uwagi:

- `application.external.yml` — tu wpisz przede wszystkim dane dostępu do bazy danych,
- `application.default.yml` — tu wprowadzaj zmienne, które powinny zostać nadpisane na serwerze i w lokalnych `application.external.yml`,
- `/resources/application.yml` — tu wprowadzaj zmienne **globalne**, np. poziomy logowania, ogólne parametry aplikacji.

### RabbitMQ

Do lokalnej pracy polecamy skorzystać z [Docker compose](<https://docs.docker.com/compose/>). Dzięki niemu uruchomienie RabbitMQ nie będzie wymagało niemal żadnej konfiguracji. Dodatkowo IntelliJ świetnie się z nim integruje.

Żeby pobrać i uruchomić kontener wystarczy przejść do pliku `docker-compose.yml` i nacisnąć zieloną strzałkę:

![docker-compose](<https://docs.logintegra.com/microservice-courier/images/readme/docker-compose-run.png>)

#### Panel administracyjny RabbitMQ

Jeżeli nie zmieniliśmy ustawień dla RabbitMQ w plikach konfiguracyjnych, po uruchomieniu `docker-compose.yml` powinniśmy mieć przez przeglądarkę dostęp do panelu administracyjnego -- [http://localhost:15672/](<http://localhost:15672/>).

Domyślny dostęp to *guest* -- *aA123456*.

### Uruchamianie

Jeśli wszystko poszło ok, aplikację możemy uruchomić z poziomu IntelliJ — guzikami *Run* lub *Debug*.

## Parametry

### Plik `application.external.yml`

- `spring`:
- `datasource`: - `url` -- adres bazy danych, np. `jdbc:postgresql://localhost:5432/microservice-courier`; - `username`, `password` -- login i hasło użytkownika bazy danych;

  - `rabbitmq`:
  - `username`, `password` -- login i hasło użytkownika `RabbitMQ`; Docker tworzy go automatycznie na podstawie `definitions.json`, więc wpisy w obu plikach muszą być zbieżne, żeby aplikacja działała poprawnie (domyślnie hasło APOLLO\_TEST\_PASSWORD z Vault);
  - `flyway` -- zawiera zmienne, których używamy w skryptach `Flyway`:
  - `placeholders`:
  - `hitachi-transport-type-name` -- to tylko nazwa, żeby nam ułatwić życie, ale warto ustawić taką, jak w bazie Apollo;

    - `hitachi-transport-type-identifier` -- `Id` typu "Kurier" firmy Hitachi z bazy Apollo; ta wartość jest istotna, ponieważ na jej podstawie będziemy wyszukiwać obiekt `TransportType` w bazie serwisu;
- `logintegra`:
- `rabbitmq`:
- `exchange` -- nazwa [Exchange](<https://www.rabbitmq.com/tutorials/amqp-concepts.html>), do którego powinny wpadać wiadomości od zewnętrznych aplikacji (jak Apollo); ta wartość musi być zbieżna z `definitions.json` (wszystkie węzły zawierające obecnie `courier.requests`).

### Plik `.env`

Plik `.env` zawiera zmienne, których możemy używać w `docker-compose.yml`:

- `RABBITMQ_USER`, `RABBITMQ_PASSWORD` -- login i hasło domyślnego użytkownika panelu administracyjnego RabbitMQ.

## RabbitMQ -- struktura

Zmieniamy trochę koncepcję pracy z RabbitMQ. Teraz struktura jest taka:

- Jedno `exchange` na wszystkie przychodzące zapytania -- o nazwie `couriers.requests`; aplikacje zewnętrzne (np. Apollo) nie decydują o tym, do której kolejki wysłać zapytanie -- robi to `exchange` za pomocą powiązań;
- Z góry określone kolejki, na razie dla wycen (`courier.pricing.queue`) oraz trackingu (`courier.tracking.queue`),
- Routing dla exchange typu **topic** [https://www.rabbitmq.com/tutorials/tutorial-five-java.html](<https://www.rabbitmq.com/tutorials/tutorial-five-java.html>), czyli z dopasowywaniem nazw *routing key*, np.:
- `*.*.pricing` -- np. `apollo-wombaty.1923000.pricing`, gdzie `1923000` to id transportu, dopasujemy do kolejki `courier.pricing.queue`,
- `*.*.tracking` -- np. `apollo-wombaty.1923000.tracking`, gdzie `1923000` to id transportu, dopasujemy do kolejki `courier.tracking.queue`.

![RabbitMQ structure](<https://docs.logintegra.com/microservice-courier/images/readme/rabbitmq-structure.png>)

Powiązanie komunikatu z kolejką wykonujemy w RabbitMQ za pomocą powiązań *bindings* między kolejką a *routing key*, które aplikacja zewnętrzna dołącza do zapytania. Np. dla `courier.pricing.queue` (określona tu jako "This queue") ustawiliśmy ją tak:

![RabbitMQ bindings](<https://docs.logintegra.com/microservice-courier/images/readme/rabbitmq-bindings.png>)

Przy domyślnym `exchange` (takim jak w application.yml), Docker powinien skonfigurować wszystkie kolejki i routing.
