Skip to content
GIS Support Cloud
Vue Python CSS JavaScript Shell Dockerfile Other
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
api
docker
frontend
.dockerignore
.env
.gitignore
README.md
docker-compose.yml
docker-production.yml

README.md

GIS Support Cloud

I. Wstęp

Projekt Cloud jest rozwiążaniem, które umożliwia szybsze wdrażanie aplikacji GISowych u klienta. Jest bogatą nakładką na Postgres wraz z PostGISem, która umożliwia zarządzanie w wygodniejszy sposób warstwami, obiektami w warstwach, użytkownikami, uprawnieniami oraz stylami. Tworzy też warstwę abstrakcji, która umożliwia szybsze rozwijanie aplikacji opratych na REST API. Jest również kompatybilny z QGIS - umożliwia pełne zarządzanie danymi (zgodnie z uprawnieniami) bezpośrednio z załadowanych warstw PostGIS.

Główne cechy projektu:

  • modułowość - moduły nie są w żaden sposób od siebie zależne, można dodawać nowe, odpinać istniejące, wszystko z poziomu jednego pliku konfiguracyjnego

  • skalowalność - przez zastosowanie Dockera istnieje możliwość replikacji kontenerów

  • przewidywalność - 100% funkcjonalności pokryta jest testami jednostkowymi oraz integracyjnymi

  • przejrzystość - zarówno kodu jak i dokumentacji

1. Architektura

Aplikacja składa się z 3 kontenerów:

  • db - jest to baza danych Postgres 12 + PostGIS 3.0 od kartozy, zmodyfikowana na nasze potrzeby (obsługa skryptu inicjalnego na więcej niż jednej bazie, ze względu na środowisko testowe). Podczas inicjalizacji kontenerów uruchamiany jest skrypt init.sql, który tworzy tabelę do styli (żeby QGIS je odpowiednio wczytał) oraz tworzy grupy użytkowników.

  • api - jest to API we Flasku oparte na Pythonie 3.7.3. Podpięty jest również Swagger dla dokumentacji. Po uruchomieniu kontenerów mamy również możliwość uruchomienia testów jednostkowych i integracyjnych.

  • redis - baza potrzebna do trzymania tokenów logowania w API, żeby nie zaśmiecać instancji postgresowej.

2. Moduły

Podstawa aplikacji składa się z 4 głównych modułów:

  • auth - Jest to moduł autoryzacji oparty na Redisie, JWT oraz postgresowych użytkownikach z hasłami. Tokeny są potrzebne do korzystania ze wszystkich modułów aplikacji. Moduł tworzy 10-minutowe tokeny odświeżane z każdym requestem o kolejne 10 minut.

  • layers = Jest to moduł warstw, którego głównym zadaniem jest tworzenie warstw, zarządzanie nimi, ich nazwami, kolumnami oraz stylami. Enpoint dodawania nowej przyjmuje jedynie pliki - obecnie wszystkie wektorowe obsługiwane przez GDAL.

  • features - Jest to CRUD do obiektów w warstwie zgodnie z uprawnieniami.

  • permissions - Składa się tylko z dwóch endpointów, jeden do listowania macierzy użytkowników i warstw (w celu stworzenia tabeli z uprawnieniami) oraz drugi do edycji uprawnienia dla danego użytkownika w danej warstwie.

3. Dodatkowe moduły

Na potrzeby wdrożenia projektu RDOŚ Lublin została stworzona "wtyczka" do API, która zawiera wszystkie wydzielone funkcjonalności. Póki co:

  • attachments - tabela do przechowywania załączników z Owncloud wraz z adnotacjami, który załącznik do której grupy użytkowników.

II. Development

  1. Wymagania:
  • Docker 19.03+

  • Docker Compose 1.21+

  1. Aby uruchomić aplikację należy uruchomić komendę:
docker-compose up
  1. Aby przeprowadzić testy, należy mieć uruchomione środowisko oraz uruchomić komendę:
docker exec -it cloud-api tests
  1. Aby przejrzeć helper do testów:
docker exec -it cloud-api tests -h

Można dowiedzieć się z niego że możemy praktykować Test Driven Development uruchamiając poszczególne grupy testów, np:

docker exec -it cloud-api tests -g permissions
  1. Każdy moduł powinien się składać z:
  • plików dokumentacyjnych pisanych w konwencji:
docs.[nazwa_encji].[ewentualnie_drugi_czlon_encji].[metoda].yml
  • pliku routings.py zawierający Blueprint wraz z endpointami

  • pliku test.py z testami wszystkich enpointów

  • (opcjonalnie) pliku models.py z modelami w Peewee dla modułu

  1. Bazy domyślnie są w trybie PERSISTENT także w celu flushowania obu baz prócz komendy:
docker-compose down -v

Należy pozbyć się persistent directories, czyli:

sudo rm -rf ./docker/db/postgres_data
sudo rm -rf ./docker/db/redis_data
  1. Sugerowana instrukcja developmentu:
  • Dodajemy nowy moduł z plikiem routings.py z endpointami zwracającymi puste dane + opcjonalnie models.py

  • Podpinamy moduł do create.py (jeśli RDOŚ to rdos/__init__.py)

  • Dodajemy nową grupę testów do pytest.ini

  • Dodajemy w nowym module plik test.py z testami pobierającymi te puste dane

  • Zapisujemy w testach co potrzebujemy i uruchamiamy ciągle nową grupę testów w celu bieżącego developmentu

  • Tworzymy i podpinamy dokumentację

  • Uruchamiamy wszystkie testy

  1. Wszystkie metody odnośnie bazy/warstw dostępne są w klasach Cloud oraz Layer w helpers/cloud.py + helpers/layer.py + helpers/style.py lub db/general.py

III. Deployment

  1. Wymagania:
  • Docker 19.03+

  • Docker Compose 1.21+

  1. Należy ustawić odpowiednie parametry w pliku .env w głównym katalogu aplikacji.

  2. Należy wykonać polecenie:

docker-compose -f docker-production.yml up -d --build

IV. Development łączony z klientem

/.env -> APP_PROD_HOST_URL = localhost /frontend/.env -> VUE_APP_PROD_HOST_URL = localhost

  1. Wygenerowanie z deweloperskiego backendu dokumentacji:
npm run api-local
  1. Uruchomienie klienta:
npm i && npm run serve
You can’t perform that action at this time.