Documentation

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`).