Konfiguracja wdrożeniowa systemu BPP (Bibliografia Publikacji Pracowników) — orkiestracja Docker Compose z monitoringiem, backupami i automatyczną konfiguracją.
- Jak zainstalować i uruchomić system BPP przy pomocy bpp-deploy
- Wspólne kroki konfiguracji
- Struktura katalogów
- Najważniejsze komendy
- Usługi
- Przenosiny serwera na inną maszynę
- Rozwiązywanie problemów
- Jak rozwijać pakiet bpp-deploy
- Licencja
Wybierz swój system operacyjny — instrukcje są podzielone na sekcje per-OS. Po zakończeniu kroków właściwych dla Twojego systemu przejdź do wspólnych kroków konfiguracji, identycznych dla wszystkich platform.
| System | Instrukcja |
|---|---|
| 🐧 Linux (Debian / Ubuntu / Fedora / Arch / openSUSE) | → przejdź do instrukcji dla Linuksa |
| 🍎 macOS (Intel + Apple Silicon) | → przejdź do instrukcji dla macOS |
| 🪟 Windows (10 / 11) | → przejdź do instrukcji dla Windows |
Otwórz Terminal (zazwyczaj skrót Ctrl+Alt+T lub znajdziesz go w menu aplikacji).
Wybierz swoją dystrybucję i wpisz podane polecenia jedno po drugim:
Debian / Ubuntu
sudo apt update
sudo apt install -y git make openssl gettextZainstaluj Docker Engine — oficjalna instrukcja dla Debian lub Ubuntu (zawiera Docker Compose).
Podpowiedź: Możesz też zainstalować Docker poleceniem
make install-dockerpo sklonowaniu repo (Debian/Ubuntu — używaapti oficjalnego repozytorium Dockera).
Fedora
sudo dnf install -y git make openssl gettextZainstaluj Docker Engine — oficjalna instrukcja dla Fedory (zawiera Docker Compose).
Arch Linux
sudo pacman -Sy --noconfirm git make openssl gettextZainstaluj Docker Engine:
sudo pacman -Sy --noconfirm docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USERWyloguj się i zaloguj ponownie, aby uprawnienia do Dockera zaczęły działać.
openSUSE
sudo zypper install -y git make openssl gettext-runtimeZainstaluj Docker Engine — oficjalna instrukcja dla SLES/openSUSE (zawiera Docker Compose).
Po zainstalowaniu narzędzi i Dockera, dodaj swojego użytkownika do grupy docker, żeby make i docker compose działały bez sudo i bez podawania hasła roota przy każdym poleceniu:
sudo usermod -aG docker $USERAby zmiana zaczęła obowiązywać, wyloguj się i zaloguj ponownie (na sesji graficznej najprościej całkowicie wylogować, a w SSH zakończyć sesję i wejść na nowo). Alternatywnie odśwież grupy w bieżącej powłoce poleceniem newgrp docker — działa tylko w tym jednym terminalu.
Sprawdź, czy działa:
docker run --rm hello-worldPolecenie powinno wykonać się bez sudo. Jeżeli zamiast tego widzisz permission denied while trying to connect to the Docker daemon socket — przelogowanie nie zostało wykonane.
Uwaga bezpieczeństwa: członkostwo w grupie
dockerjest faktycznie równoważne uprawnieniom roota na hoście (przez Dockera można zamontować/i wyjść z kontenera). Dodawaj do tej grupy tylko zaufane konta administratorów.
Sklonuj repozytorium i przejdź do katalogu:
git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deployOtwórz Terminal — znajdziesz go w Finderze pod ścieżką Programy > Narzędzia > Terminal (albo wyszukaj "Terminal" przez Spotlight: Cmd+Spacja).
Zainstaluj Xcode Command Line Tools (zawiera git i make). Wpisz w Terminalu:
xcode-select --installPojawi się okno z prośbą o potwierdzenie — kliknij Zainstaluj i poczekaj na zakończenie.
Zainstaluj Docker Desktop dla macOS — pobierz ze strony (wybierz wariant zgodny z Twoim Makiem: Apple Silicon dla M1/M2/M3/M4 lub Intel dla starszych modeli), otwórz plik .dmg i przeciągnij Docker do folderu Programy. Uruchom Docker Desktop i poczekaj, aż ikona w pasku menu przestanie się animować.
Zainstaluj envsubst (potrzebny do generowania konfiguracji). Jeśli nie masz jeszcze Homebrew, najpierw go zainstaluj, a potem wpisz w Terminalu:
brew install gettextSklonuj repozytorium i przejdź do katalogu:
git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deployPobierz i zainstaluj (klikając "Dalej" w instalatorach):
- Git for Windows — dostarcza Git Bash, czyli terminal z narzędziami Unix
- Docker Desktop for Windows — po instalacji uruchom Docker Desktop i poczekaj, aż ikona w zasobniku przestanie się animować
Zainstaluj GNU Make. Otwórz PowerShell jako Administrator (kliknij prawym przyciskiem na menu Start > "Terminal (Administrator)" lub "Windows PowerShell (Administrator)") i wpisz:
choco install makeJeśli nie masz Chocolatey, możesz zamiast tego użyć Scoop:
scoop install makeOtwórz Git Bash (znajdziesz go w menu Start po wpisaniu "Git Bash") i sklonuj repozytorium:
git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deployWażne: Od tego momentu wszystkie komendy
makeuruchamiaj w Git Bash, nie w CMD ani PowerShell.
Poniższe kroki wykonujesz po zakończeniu instrukcji właściwych dla Twojego systemu operacyjnego. Są identyczne dla Linux, macOS i Windows.
makePrzy pierwszym uruchomieniu make zapyta o ścieżkę do katalogu konfiguracyjnego — musi znajdować się poza repozytorium. Jego nazwa stanie się nazwą projektu Docker Compose.
=== BPP Deploy - pierwsze uruchomienie ===
Podaj sciezke do katalogu konfiguracyjnego instancji BPP.
Katalog musi znajdowac sie POZA repozytorium.
Przyklad: /home/deploy/publikacje-uczelnia
Sciezka: /home/deploy/moja-instancja
make automatycznie:
- utworzy strukturę katalogów konfiguracyjnych,
- skopiuje szablonowe pliki z
defaults/, - wygeneruje losowe hasła do bazy danych,
- utworzy plik
.envz konfiguracją.
Otwórz plik .env z katalogu konfiguracyjnego w dowolnym edytorze tekstu (np. Notepad, VS Code, nano, vim):
# Ścieżka wyświetli się po pierwszym uruchomieniu make, np.:
# /home/deploy/moja-instancja/.env
Co trzeba zmienić w .env:
DJANGO_BPP_HOSTNAME— właściwa nazwa hosta (np.publikacje.uczelnia.pl)DJANGO_BPP_CSRF_EXTRA_ORIGINS— dozwolone originy CSRF- Sprawdź wygenerowane hasła (opcjonalnie)
Dodaj certyfikaty SSL (lub wygeneruj samopodpisane):
# Opcja A: własne certyfikaty — skopiuj cert.pem i key.pem
# do podkatalogu ssl/ w katalogu konfiguracyjnym
# Opcja B: samopodpisane certyfikaty (snakeoil) do testów
make generate-snakeoil-certsmake runPo uruchomieniu make run główny serwis jest dostępny przez webserver (Nginx), który wystawia standardowe porty HTTP i HTTPS:
80:80443:443
Na Docker Desktop pod macOS oznacza to, że porty są mapowane na hosta macOS. Aplikację otwierasz więc w przeglądarce przez adres hosta, a nie przez wewnętrzne porty kontenerów.
Zalecane warianty konfiguracji lokalnej:
- ustaw
DJANGO_BPP_HOSTNAME=localhosti otwórzhttps://localhost/ - albo ustaw własną nazwę, np.
bpp.local, dodaj ją do/etc/hosts, a następnie otwórzhttps://bpp.local/
Uwaga: Nginx akceptuje tylko hostname zgodny z DJANGO_BPP_HOSTNAME. Jeśli w konfiguracji ustawisz inną nazwę hosta, wejście przez localhost może nie działać poprawnie mimo poprawnego mapowania portów.
Przy pierwszym uruchomieniu, jeśli baza danych jest pusta, aplikacja automatycznie przekieruje do /setup/. Jest to oczekiwane zachowanie kreatora konfiguracji początkowej, w którym tworzysz pierwsze konto administratora.
Dodatkowe narzędzia administracyjne i monitoring nie są wystawiane jako osobne porty hosta. Są dostępne przez Nginx pod ścieżkami:
https://<hostname>/grafana/https://<hostname>/flower/https://<hostname>/dozzle/
~/
├── bpp-deploy/ # To repozytorium
│ ├── .env # Wskazuje katalog konfiguracyjny
│ ├── Makefile
│ ├── docker-compose.*.yml
│ ├── mk/ # Moduły Makefile
│ ├── defaults/ # Szablonowe pliki konfiguracyjne
│ └── tests/
│
├── moja-instancja/ # Katalog konfiguracyjny (BPP_CONFIGS_DIR)
│ ├── .env # Zmienne aplikacyjne (hasła, hostname)
│ ├── ssl/ # Certyfikaty SSL
│ ├── alloy/ # Konfiguracja Grafana Alloy
│ ├── prometheus/ # Konfiguracja Prometheus
│ ├── grafana/provisioning/ # Dashboardy i datasources Grafana
│ ├── rclone/ # Konfiguracja backupów
│ └── dozzle/ # Użytkownicy Dozzle
│
└── backups/ # Backupy baz danych
make help # Pełna lista wszystkich targetów Make (źródło prawdy)make run # Pełne wdrożenie (pull, build, configs, up)
make up # Start wszystkich usług (force recreate)
make up-quick # Szybki start bez recreation
make refresh # prune + pull + recreate (po update obrazu)
make wait # Czeka na build z GH Actions, potem make refresh
make stop # Zatrzymaj usługi
make restart-appserver # Restart serwera aplikacjimake migrate # Migracje Django (bezpiecznie zatrzymuje workery)
make db-backup # Backup bazy (równoległy pg_dump, tar.gz)
make dbshell # Django database shell
make dbshell-psql # Bezpośredni psql
make upgrade-postgres # Upgrade major wersji PostgreSQL (np. 16.13 -> 18.3)make health # Szybki healthcheck wszystkich usług
make logs-appserver # Logi serwera aplikacji
make logs-celery # Logi workerów Celery
make ps # Lista kontenerów
make celery-stats # Statystyki zadań Celerymake update-configs # Regeneruj datasources.yaml (envsubst)
make update-ssl-certs # Przeładuj nginx po zmianie certyfikatów
make init-configs # Uzupełnij brakujące pliki w katalogu konfiguracyjnym
make configure-resources # Dostrój limity RAM/CPU dla wszystkich serwisów
make generate-snakeoil-certs # Wygeneruj samopodpisane certyfikaty SSLPodczas pierwszego uruchomienia make skrypt configure-resources jest odpalany automatycznie — wykrywa RAM i liczbę rdzeni hosta, proponuje proporcjonalny podział budżetu między 7 serwisów wysokiego ryzyka (dbserver, appserver, workerserver-general/denorm, redis, loki, prometheus) i pyta użytkownika o akceptację każdej wartości. Jeżeli odstąpisz od zaproponowanego defaultu dla któregoś serwisu, pozostałe mają swój budżet proporcjonalnie powiększony lub zmniejszony.
Docker traktuje limit RAM jako twardy (przekroczenie → OOM kill), a CPU jako miękki (throttling bez zabijania). RAM ustawiaj z zapasem.
Wynik ląduje w $BPP_CONFIGS_DIR/.env jako zmienne DBSERVER_MEM_LIMIT, APPSERVER_MEM_LIMIT itd. Możesz wrócić i przekonfigurować w każdej chwili uruchamiając make configure-resources ręcznie.
Kontener dbserver używa obrazu iplweb/bpp_dbserver:psql-<MAJOR.MINOR>. Wersja jest sterowana zmienną DJANGO_BPP_POSTGRESQL_VERSION w $BPP_CONFIGS_DIR/.env (obok jest auto-derived DJANGO_BPP_POSTGRESQL_VERSION_MAJOR używana przez backup-runnera postgres:<major>-alpine). Aktualna lista tagów: hub.docker.com/r/iplweb/bpp_dbserver/tags (np. 16.13, 17.9, 18.3).
Domyślna wersja: 16.13. Wybór wersji następuje przy pierwszym uruchomieniu make — skrypt init-configs zapyta o Wersja PostgreSQL [16.13]:. Możesz wpisać dowolną dostępną na Docker Hub.
Format PGDATA jest binarnie kompatybilny w obrębie tego samego majora, więc wystarczy zmiana tagu i restart:
# 1. W $BPP_CONFIGS_DIR/.env zmień: DJANGO_BPP_POSTGRESQL_VERSION=16.14
# 2. Pobierz nowy obraz i odśwież kontener:
docker compose pull dbserver
docker compose up -d dbserverMiędzy różnymi major wersjami PostgreSQL nie ma binarnej kompatybilności formatu PGDATA — każdy nowy kontener musi wystartować na pustym, świeżo zainicjalizowanym wolumenie. Dane przenosi się metodą logical dump & restore:
make upgrade-postgresSkrypt interaktywnie wykonuje 9 kroków (dump → kopia volume → bump .env → initdb na nowym majorze → restore → migracje), z automatycznym rollbackiem w razie nieudanego startu nowej bazy oraz trybem resume (--from-step=N) pozwalającym wznowić po błędzie bez powtarzania długiego dumpu.
Wymagania:
- Obraz
iplweb/bpp_dbserver:psql-<nowa_wersja>musi być opublikowany na Docker Hub. - Wolne miejsce: ~2.5× rozmiar PGDATA (tarball + kopia starego volume).
- Stack musi być uruchomiony (
make up), żeby wykonaćpg_dump.
Pełna dokumentacja kroków, rollbacku i resume:
bash scripts/upgrade-postgres.sh --helpTryb external (BPP_DATABASE_COMPOSE=docker-compose.database.external.yml): upgrade samej bazy wykonujesz po swojej stronie (managed service, RDS blue/green, pg_upgradecluster itp.), a skrypt tylko synchronizuje DJANGO_BPP_POSTGRESQL_VERSION + _MAJOR i odświeża sentinel/backup-runner.
make db-backup # Pojedynczy pg_dump (równoległy, tar.gz)
make backup-cycle # Pełen cykl: pg_dump + tar mediów + rclone + powiadomienia
make rclone-config # Konfiguracja zdalnego backupu (Google Drive, S3, ...)
make rclone-sync # Wymuszona synchronizacja z chmurą
make rclone-check # Sprawdzenie spójności kopii zdalnejCodzienny backup uruchamia Ofelia o 02:30 — opisane szerzej w sekcji Usługi.
make release # Tag + push: YYYY.MM.DD lub YYYY.MM.DD.N (calendar versioning)
make version # Wyświetl bieżącą wersjęmake base-host-update-upgrade # Aktualizacja systemu (apt update + full-upgrade)
make base-host-reboot # Restart hosta
make install-docker # Instalacja Dockera na hoście| Usługa | Opis |
|---|---|
| appserver | Serwer aplikacji Django |
| authserver | Serwer uwierzytelniania dla nginx |
| dbserver | PostgreSQL |
| webserver | Nginx (reverse proxy + static files) |
| redis | Cache, broker Celery i result backend |
| workerserver-general | Ogólne zadania Celery |
| workerserver-denorm | Zadania denormalizacji |
| denorm-queue | Bridge PostgreSQL LISTEN → Celery (single instance!) |
| celerybeat | Harmonogram zadań okresowych |
| flower | UI monitorowania Celery (/flower) |
| grafana | Dashboardy i wizualizacje (/grafana) |
| prometheus | Metryki |
| loki | Agregacja logów |
| alloy | Kolektor logów z kontenerów Docker |
| dozzle | Przeglądarka logów w czasie rzeczywistym (/dozzle) |
| rclone | Backup do chmury |
| ofelia | Cron dla Dockera |
Procedura przeniesienia działającej instancji BPP na nowy host (np. wymiana sprzętu, migracja do innego data center, klonowanie środowiska produkcyjnego na zapasowe). Sprowadza się do trzech katalogów + dwóch komend.
-
Zrób świeży backup pary baza + media:
cd ~/bpp-deploy make backup
make backupuruchamiadb-backup(równoległypg_dump -Fd, spakowany dotar.gz) imedia-backup(zawartość volumemediajakotar.gz). Oba archiwa lądują w$DJANGO_BPP_HOST_BACKUP_DIRz timestampem (db-backup-YYYYMMDD-HHMMSS.tar.gz,media-backup-YYYYMMDD-HHMMSS.tar.gz). -
Skopiuj na nową maszynę trzy katalogi (np. przez
rsync,scp, dysk zewnętrzny):~/bpp-deploy/— repozytorium (zawiera.envwskazujący na katalog konfiguracyjny)$BPP_CONFIGS_DIR— katalog konfiguracyjny instancji (np.~/publikacje-uczelnia/z.env, certyfikatami SSL, konfiguracją Grafany itd.)$DJANGO_BPP_HOST_BACKUP_DIR— katalog z backupami (potrzebny tylko ten najświeższy z punktu 1, ale prościej skopiować całość)
Przykład z
rsyncprzez SSH (z aktualnego hosta na nowy):rsync -avzP ~/bpp-deploy/ nowy-host:~/bpp-deploy/ rsync -avzP ~/publikacje-uczelnia/ nowy-host:~/publikacje-uczelnia/ rsync -avzP ~/backups/ nowy-host:~/backups/
Ścieżki absolutne w
.env(BPP_CONFIGS_DIR,DJANGO_BPP_HOST_BACKUP_DIR) muszą się zgadzać po obu stronach — albo skopiuj do tych samych ścieżek, albo edytuj.envna nowej maszynie po przeniesieniu.
-
Zainstaluj zależności hosta zgodnie z sekcją Linux / macOS / Windows — Docker Engine,
make,git,gettext, dodanie użytkownika do grupydocker. Nie uruchamiajmakeanimake init-configs— masz już skopiowaną konfigurację, świeżyinit-configsrozjedzie hasła z dumpem. -
Przywróć dane z backupu:
cd ~/bpp-deploy make restore
Skrypt
restore.shautomatycznie wybiera najświeższą parędb-backup+media-backupz katalogu backupów (możesz też podać--pickdo interaktywnego wyboru zfzf/menu albo--timestamp=YYYYMMDD-HHMMSS). Przed destruktywnym restorem robi safety-backup aktualnej pustej bazy, więc procedura jest odwracalna. -
Zweryfikuj:
make health make logs-appserver
Otwórz aplikację w przeglądarce — powinieneś zobaczyć dokładnie ten sam stan, co na starej maszynie w momencie
make backup.
- DNS / certyfikaty SSL — jeśli zmienia się hostname, zaktualizuj
DJANGO_BPP_HOSTNAMEiDJANGO_BPP_CSRF_EXTRA_ORIGINSw$BPP_CONFIGS_DIR/.env, podmień certyfikaty w$BPP_CONFIGS_DIR/ssl/i uruchommake update-ssl-certs. - rclone — konfiguracja zdalnych backupów już jest w
$BPP_CONFIGS_DIR/rclone/, działa od razu po przeniesieniu. - Cron Ofelia — niczego nie trzeba przepisywać, harmonogram jest w pliku
docker-compose.application.ymlz repozytorium.
make backup zapisuje tylko bazę danych i wolumeny mediów. Loki/Prometheus/Grafana (logi i metryki historyczne) nie są przenoszone — po starcie na nowym hoście zaczynają od pustego stanu. Jeśli zależy ci na historii monitoringu, skopiuj dodatkowo wolumeny prometheus_data, loki_data i grafana_data (przy zatrzymanym stacku, np. przez docker run --rm -v <vol>:/data alpine tar czf - /data | ssh nowy-host 'cat > vol.tar.gz').
Symptom: make up kończy się błędem bind: address already in use na webserver. Lokalna instalacja nginx, Apache lub innego serwera zajmuje porty.
# Sprawdź, kto trzyma port:
sudo lsof -iTCP:80 -sTCP:LISTEN
sudo lsof -iTCP:443 -sTCP:LISTENZatrzymaj kolidującą usługę (sudo systemctl stop nginx) albo zmień mapowanie portów w docker-compose.infrastructure.yml (np. 8080:80, 8443:443) — pamiętaj o zaktualizowaniu URL-i, którymi otwierasz aplikację.
Symptom: po make generate-snakeoil-certs przeglądarka blokuje stronę z komunikatem NET::ERR_CERT_AUTHORITY_INVALID lub podobnym.
To certyfikat samopodpisany — przewidziany do testów lokalnych. Opcje:
- Lokalnie: kliknij „Zaawansowane" → „Mimo to przejdź do strony" (Chrome/Edge) lub „Zaakceptuj ryzyko" (Firefox).
- Produkcyjnie: wystaw prawdziwy certyfikat przez Let's Encrypt / komercyjne CA i podmień
cert.pem/key.pemw katalogussl/w$BPP_CONFIGS_DIR. Następniemake update-ssl-certs.
Symptom: Got permission denied while trying to connect to the Docker daemon socket.
Twój użytkownik nie należy do grupy docker:
sudo usermod -aG docker $USER
# Wyloguj się i zaloguj ponownie, albo:
newgrp dockerSymptom: aplikacja zamiast /setup/ rzuca błąd 500 lub przekierowuje na login. Najczęstsza przyczyna: migracje nie zostały uruchomione na pustej bazie.
make migrate
make logs-appserver # Sprawdź, czy migracje przeszły bez błęduSymptom: make ps pokazuje status restarting albo unhealthy.
make health # Globalny przegląd
make logs-<service> # Zastąp <service> nazwą z make ps
docker compose logs --tail=200 <service>Najczęstsze przyczyny: brak migracji bazy (uruchom make migrate), brak połączenia z Redis (sprawdź czy redis jest healthy), niepoprawne wartości w .env.
Symptom: nowe usługi się nie pojawiają, obrazy są stare, .env nie ma nowych zmiennych.
make init-configs # Uzupełnia brakujące zmienne w .env (idempotentne)
make refresh # prune + pull + recreate całego stackuBackwards compatibility jest gwarantowana — bpp-deploy zawsze startuje na starym .env (patrz CLAUDE.md, sekcja „Backwards Compatibility"). Jeśli mimo to coś nie działa, zgłoś issue.
Zakres: ta sekcja dotyczy wyłącznie rozwoju
bpp-deploy— czyli orkiestracji Docker Compose, Makefile, skryptów konfiguracyjnych i monitoringu opisanych w tym repozytorium.Rozwój samej aplikacji BPP (kod Django w
/src/, modele, widoki, importery, integracje z PBN, ORCID itd.) odbywa się w osobnym repozytorium: github.com/iplweb/bpp — tam też znajdziesz dokumentację dla developerów aplikacji.
./tests/test_makefile.shTesty weryfikują orkiestrację bpp-deploy:
- first-run setup (tworzenie konfiguracji, generowanie haseł)
- idempotentność
init-configs - losowość haseł między instancjami
- dostępność targetów Make w trybie normalnym
- poprawność bind mountów w docker-compose
- brak mechanizmów SCP w konfiguracji
Repozytorium używa pre-commit z następującymi hookami:
- trailing-whitespace, end-of-file-fixer — formatowanie
- check-yaml — walidacja YAML
- check-merge-conflict — wykrywanie konfliktów merge
- detect-private-key — blokada kluczy prywatnych
- shellcheck — linter bash
- TruffleHog — wykrywanie sekretów i haseł
pip install pre-commit
pre-commit installMIT

