diff options
| -rw-r--r-- | .envrc.sample | 9 | ||||
| -rw-r--r-- | README.md | 134 |
2 files changed, 143 insertions, 0 deletions
diff --git a/.envrc.sample b/.envrc.sample new file mode 100644 index 0000000..5e4b694 --- /dev/null +++ b/.envrc.sample @@ -0,0 +1,9 @@ +export LIGA_RSYNC_OPTS= +export LIGA_REMOTE_WWW_DIR='user@webserver.example.com:/var/www/path/on/remote/server' + +export LIGA_S3_BUCKET='s3://s3-bucket-name/' + +export LIGA_MYSQL_CONNECTION_OPTS='-h mysql_host -u mysql_user' + +export LIGA_BUTLER_FINISHED_ROUND=0 +export LIGA_BUTLER_FINISHED_SEGMENT=0 diff --git a/README.md b/README.md new file mode 100644 index 0000000..e37f758 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# Ligi centralne PZBS - koordynacja + +Zestaw skryptów do obsługi lig centralnych PZBS. + +Podzielony na kilka modułów, każdy z nich wywoływany jako osobny *target* polecenia `make`. + +Moduły czytają część konfiguracji ze zmiennych środowiskowych. Przykładowy zestaw zmiennych używanych w projekcie znajduje się w pliku `.envrc.sample`. + +W repozytorium są podmoduły, pamiętaj o `git submodule update --init --recursive` po wyciągnięciu tego kodu. + +## Kopie zapasowe stron z wynikami + +Moduł tworzy w katalogu `http` kopie zapasowe plików wyników, ściagane z serwera. W założeniu - ma to robić bez interakcji z użytkownikiem. + +Opcjonalnie, dostarcza również skryptu, który równie bezobsługowo wersjonuje zmiany w repozytorium Git. + +### Wymagania wstępne + + * dostęp do serwera wyników po SSH + * rsync + * opcjonalnie: git + +### Wywołanie + +Kopia zapasowa: + +`make pull` + +Kopia zapasowa z wersjonowaniem zmian: + +`make autocommit` + +### Konfiguracja + +Zmienne środowiskowe: + * `LIGA_REMOTE_WWW_DIR`: kopletna zdalna ścieżka do backupu (`user@serwer:/ścieżka`) + * `LIGA_RSYNC_OPTS`: dodatkowe parametry wywołania programu `rsync` (np. wczytujące klucz prywatny do uwierzytelnienia) + +W przypadku wersjonowania kopii zapasowych, w katalogu wyjściowym `http` musi byćzainicjowane repozytorium Git ze skonfigurowanym zdalnym repozytorium docelowym. + +## Kopie zapasowe baz danych turniejów + +Moduł wczytuje do lokalnie skonfigurowanej bazy danych, zrzuty baz turniejów, dostarczane przez sędziów w kotłach. + +Wprowadza do zrzutów często potrzebne poprawki (jak np. uzupełnienie tabeli `logoh`), a także umożliwia zdefiniowanie własnych poleceń, wykonywanych na każdej z baz danych po jej wgraniu ze zrzutu. + +### Wymagania wstępne + + * s3cmd + * klient MySQL + +Zrzuty baz danych muszą zostać niezależnie pozyskane od sędziów poszczególnych kotłów i wrzucone do jednego wiaderka S3, np. używając [Spedytora](https://github.com/emkael/spedytor/). + +### Wywołanie + +`make dumps` + +### Konfiguracja + +Zmienne środowiskowe: + + * `LIGA_MYSQL_CONNECTION_OPTS`: komplet przełączników polecenia `mysql` pozwalający podłączyć się do docelowego (lokalnego) serwera MySQL + * `LIGA_S3_BUCKET`: URI wiaderka S3, w którym trzymane są zrzuty + +Pliki konfiguracyjne: + + * `dumps/.s3config`: konfiguracja klienta `s3cmd`, można wygenerować ją poleceniem `s3cmd --configure -c dumps/.s3config` + * `dumps/.mapping`: mapowanie nazw plików zrzutów na docelowe bazy danych, do których zrzuty są wgrywane, każdy wiersz to jeden turniej, w każdym wierszu najpierw pojawia się nazwa bazy danych, a następnie, po odstępie, nazwa pliku relatywna względem `./dumps/` (domyślnie zrzuty trafiają do katalogu `./dumps/sync/`) + * `dumps/.queries`: spis poleceń SQL wykonywanych na każdej bazie danych po wgraniu jej do lokalnego serwera, po jednym poleceniu na wiersz + +## Moduł butlera + +Zbija wiele turniejów w jeden, w celu wyliczenia wspólnego butlera. + +### Wymagania wstępne + + * python, wersji dowolnej (testowane pod 2.7.18 i 3.8.6) + * klient MySQL + * założony prawidłowo w pakiecie JFR Teamy turniej docelowy dla wspólnej klasyfikacji (choć jego parametry startowe - liczba teamów, stołów itp. nie muszą być wcześniej poprawnie ustawione) + +### Wywołanie + +`make butler` + +Wywołany zostanie również moduł synchronizujący i ładujący zrzuty baz danych. + +Ręczne wywołanie samego scalania polega na uruchomieniu skryptu `butler/butler.py` z parametrem odpowiadającym właściwemu zestawowi zbijanych turniejów (patrz: Konfiguracja poniżej) i wgraniu wynikowego skryptu SQL do docelowego serwera bazy danych. + +Na tak spreparowanym turnieju docelowym trzeba później **ręcznie** (tj. JFR Teamy Adminem) dokonać zamknęcia niezamkniętych rund (wtedy odbywa się właściwe przeliczanie łącznego butlera) oraz wysłania stron statycznych. + +### Konfiguracja + +Zmienne środowiskowe: + + * `LIGA_MYSQL_CONNECTION_OPTS`: komplet przełączników polecenia `mysql` pozwalający podłączyć się do docelowego (lokalnego) serwera MySQL + * `LIGA_BUTLER_FINISHED_ROUND`, `LIGA_BUTLER_FINISHED_SEGMENT`: opcjonalne, jeśli ustawione, docelowy turniej cofany jest tylko do zdefiniowanego momentu, a nie do samego początku (żeby nie przeliczać wszystkich rund po kolei za każdym razem) + +Plik konfiguracyjny `config.json`: + + * plik formatu JSON, zawierający obiekt słownikowy + * klucz `__groups` określa nazwy "grup", tj. prefiksy, które są doklejane do nazw teamów w wynikowym turnieju, jeśli chcemy w zbiorczym butlerze rozróżnić, skąd pochodzą źródłowe drużyny - jest to prosty słownik wartości `"baza_danych": "prefiks"` + * klucz `__queries` określa dodatkowe polecenia SQL, które wykonywane są na **źródłowej** bazie danych przed poleceniami wklejającymi dane do bazy docelowej, może służyć np. do ustawienia BYEów czy korekty nierównolicznych grup, zaleca się modyfikować wyłącznie tabele, dla których w trakcie zbijania tworzone są **kopie** (prefiksowane podkreślnikiem, np. `_matches` czy `_teams`) - i działać na tych kopiach - jest to słownik formatu `"baza_danych": ["polecenie_1", "polecenie_2"]` + +Pozostałe klucze słownika w `config.json` przyjmują następującą postać: + +``` +"identyfikator_turnieju": { + "source": [ + "źródłowa_baza_danych_1", + "źródłowa_baza_danych_2", + "źródłowa_baza_danych_3" + ], + "output": "docelowa_baza_danych" +} +``` + +W takiej konfiguracji `identyfikator_turnieju` jest parametrem wywołania skryptu `butler/butler.py`, a źródłowe turnieje zbijane są w zdefiniowanej kolejności i umeiszczane w docelowej bazie danych. + +Dodatkowo, w pliku `butler/butler.py` zakładane są następujące maksymalne rozmiary turniejów źródłowych: + * zmienna `TABL_STEP` (liczba stołów w turnieju): 8 + * zmienna `TEAM_STEP` (liczba teamów w turnieju): 16 + * zmienna `PLAYER_STEP` (liczba zawodników w turnieju): 400 + +## "Australijskie" butlery + +Moduł zewnętrzny, liczący i wysyłający butlery znormalizowane dla określonych turniejów. + +Szczegółowa dokumentacja: [pzbs-liga-ausbutler](https://github.com/emkael/pzbs-liga-ausbutler). + +### Wywołanie + +`make ausbutler` + +Przeliczone zostaną wszystkie butlery zdefiniowane w podmodule `pzbs-liga-ausbutler` (z katalogu `ausbutler`). |