Opis instalacji Docker'a: https://docs.docker.com/install
Opis instalacji docker-compose: https://docs.docker.com/compose/install
Do zarządzania kodem źródłowym projektu używany jest system kontroli wersji Git. Instrukcja instalacji systemu znajduje się pod adresem: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
$ git clone https://gitlab.dane.gov.pl/mcod/backend.git
$ cd backend
$ git clone https://gitlab.dane.gov.pl/mcod/frontend.git
$ git clone https://gitlab.dane.gov.pl/mcod/test-data.git
Aby projekt działał prawidłowo, należy skopiować zawartość pliku env.sample do nowo utworzonego pliku .env.
Uwaga: Do poprawnego dzialania biblioteki django-searchable-encrypted-fields, należy wygenerować samodzielnie encryption key
biblioteką secrets secrets.token_hex(32)
. Jest to konieczne, ponieważ biblioteka szyfruje i odszyfrowuje pola z bazy danych (działa w dwie strony). Klucz należy dodać do pliku env zmiennej FIELD_ENCRYPTION_KEYS. Zmienna odczytywana jest jako lista, dlatego kolejne klucze dodaje sie przecinkiem na początku stringa. (https://pypi.org/project/django-searchable-encrypted-fields/). Przykład: FIELD_ENCRYPTION_KEYS=new_key,some_old_key
Aby projekt działał prawidłowo, należy skopiować zawartość pliku mcod/settings/local.py.sample
do nowo utworzonego pliku mcod/settings/local.py
.
Konfiguracja Django realizowana jest na podstawie ustawień z pliku mcod/settings/base.py
, które są nadpisywane ustawieniem z pliku mcod/settings/local.py
.
Proces budowania środowiska może trwać nawet kilkadziesiąt minut w zależności od hosta.
$ docker compose up -d mcod-db
$ docker compose exec mcod-db dropdb mcod --username=mcod
$ docker compose exec mcod-db createdb mcod -O mcod --username=mcod
$ docker compose up -d mcod-db mcod-elasticsearch mcod-nginx mcod-rabbitmq mcod-rdfdb mcod-redis
Uwaga: Aby kontenery uruchomiły się poprawnie, należy dodać zmienną środowiskową do pliku .env: PWD określającą ścieżkę absolutną do projektu.
W przypadku korzystania z IDE PyCharm (Professional) możliwe jest dodanie konfiguracji dotyczącej zarządzania kontenerami.
Więcej: https://www.jetbrains.com/help/pycharm/docker-compose.html#working
$ pip install -I pipenv==2022.10.12
$ pipenv run pip install setuptools"<58"
$ pipenv install --dev
$ exit
$ pipenv shell
(backend) $ python manage.py init_mcod_db
(backend) $ python manage.py search_index --rebuild -f
(backend) $ python manage.py validate_resources --async
W przypadku użycia flagi async
należy najpierw uruchomić Celery (instrukcja niżej), gdyż rewalidacja będzie odbywać się w ramach tasków Celery.
Aby uruchomić wszystkie usługi w katalogu projektu backend
wykonaj:
$ docker compose up -d
Opcjonalnie można uruchamiać tylko wybrane usługi wyspecyfikowane jako parametr polecenia:
$ docker compose up -d mcod-db mcod-elasticsearch
Aby zatrzymać wybraną usługę, w katalogu projektu backend
wykonaj:
$ docker compose stop mcod-elasticsearch
Aby zatrzymać usługę łącznie z usunięciem kontenera, w katalogu backend
wykonaj:
$ docker compose down mcod-db
Aby zatrzymać usługę łącznie z usunięciem kontenera oraz powiązanych z nim wolumenów (całkowite usunięcie usługi), w katalogu backend
wykonaj:
$ docker compose down -v mcod-db
Dodaj mapowanie adresu IP:
Adres IP: 172.18.18.100
Do nazw maszyn:
mcod.local
api.mcod.local
admin.mcod.local
cms.mcod.local
Oraz dodaj mapowanie adresu IP:
Adres IP: 172.18.18.23
Do maszyny:
mcod-rdfdb
Aby biblioteka certifi poprawnie używała certyfikatów nginx, należy dodać odpowiedni wpis do pliku cacert.pem. Aby to zrobić, należy uruchomić komendę:
(backend) $ python manage.py configure_nginx_certs
Poza specyficznymi dla każdej usługi zmiennymi środowiskowymi, dla wszystkich usług należy ustawić zmienne środowiskowe:
PYTHONUNBUFFERED=1;
ENABLE_VAULT_HELPERS=no;
ENVIRONMENT=local;
NO_REPLY_EMAIL=env@test.local;
ALLOWED_HOSTS=*;
BASE_URL=https://mcod.local;
API_URL=https://api.mcod.local;
ADMIN_URL=https://admin.mcod.local;
CMS_URL=https://cms.mcod.local;
API_URL_INTERNAL=https://api.mcod.local;
DEBUG=yes;
COMPONENT=admin;
BOKEH_DEV=True;
BOKEH_RESOURCES=cdn;
BOKEH_ALLOW_WS_ORIGIN=mcod.local;
BOKEH_LOG_LEVEL=debug;
BOKEH_PY_LOG_LEVEL=debug;
BOKEH_MINIFIED=False;
BOKEH_VALIDATE_DOC=False;
BOKEH_PRETTY=True;
STATS_LOG_LEVEL=DEBUG;
DJANGO_ADMINS=Jon Doe:jond@test.com,Jane Smith:jane.smith@example.com.pl;
DATASET_ARCHIVE_FILES_TASK_DELAY=1;
(backend) $ python manage.py runserver 0:8001
Po uruchomieniu usługi, pod adresem https://admin.mcod.local będzie dostępny panel administracyjny. Możliwe jest zalogowanie się na konta 2 użytkowników:
- login: admin@mcod.local, hasło:testadmin123!
- login: pelnomocnik@mcod.local, hasło: User123!
(backend) $ python -m werkzeug.serving --bind 0:8000 --reload --debug mcod.api:app
COMPONENT=cms;
(backend) $ python manage.py runserver 0:8002
Po uruchomieniu usługi będzie ona dostępna pod adresem https://cms.mcod.local/admin/
Instrukcja uruchomienia frontend w pliku frontend/README.md
Do prawidłowego funkcjonowania niezbędne jest uruchomienie usługi API.
COMPONENT=celery;
Uruchomienie usługi jest niezbędne, jeżeli zamierzamy korzystać z zadań asynchronicznych, takich jak wysyłanie maili czy walidacja plików zasobów.
(backend) $ python -m celery --app=mcod.celeryapp:app worker -l DEBUG -E -Q default,resources,indexing,periodic,newsletter,notifications,search_history,watchers,harvester,indexing_data
-
Tworzenie wykazu głównego: dla zadania realizującego tworzenie wykazu głównego DGA niezbędne jest ustawienie zmiennej środowiskowej określającej id Instytucji będącej jego właścicielem:
MAIN_DGA_DATASET_OWNER_ORGANIZATION_PK=<organization_pk>
(backend) python manage.py set_up_forum --file /.../backend/data/discourse/settings.json --theme_path /.../backend/data/discourse/discourse-otwarte-dane-theme.zip --password bitnami123 --username user
Po wykonaniu powyższej komendy utworzy się plik api_key.txt w folderze mcod/. Zawartość pliku należy przekopiować i wkleić do zmiennej DISCOURSE_API_KEY w pliku .env
Pierwsza konfiguracja nie wykonała poprawnie kroku sync_user, bo brakowało utworzonego klucza API_KEY, stąd trzeba wykonać ten krok ponownie.
(backend) python manage.py set_up_forum --step_name sync_users
(backend) $ tox
(backend) $ python manage.py search_index --rebuild
(backend) $ python manage.py validate_resources --where 'id in (<id_1,...,id_N>)'
(backend) $ python manage.py validate_resources --where id=<id>
(backend) $ python manage.py index_file --pks <id_1,...,id_N>
Aby pre-commit
uruchamiał się przy każdym commicie, trzeba go zainstalować:
(backend) pre-commit install
Dodanie pliku/plików jest niezbędne do sprawdzenia ich poprawności:
$ git add <filename>
Uruchomienie pre-commit sprawdzającego m.in. poprawność stylu i importów.
(backend) $ pre-commit run
Używamy black do zachowania stylu kodu.
Konfiguracja jest obecna tylko w .pre-commit-config.yaml
, ponieważ nie używamy pyproject.toml
.
git blame
może ignorować commit z masowym reformatowaniem kodu, zobacz opcję --ignore-revs-file .git-blame-ignore-revs
Po zmianie tłumaczeń w pliku django.po
należy przejść do katalogu projektu,
w którym znajduje się plik manage.py
. Następnie należy uruchomić polecenie:
(venv) $ python manage.py compilemessages