README.md

BPP Deploy

Konfiguracja wdrożeniowa systemu BPP (Bibliografia Publikacji Pracowników) — orkiestracja Docker Compose z monitoringiem, backupami i automatyczną konfiguracją.

📖 Pełna dokumentacja: iplweb.github.io/bpp-deploy

Wsparcie komercyjne zapewnia

---

To repozytorium zawiera wyłącznie warstwę wdrożeniową (Docker Compose, Makefile, skrypty, monitoring). Kod aplikacji Django żyje w osobnym repozytorium iplweb/bpp i wewnątrz obrazów iplweb/*.

To README pokazuje jak zainstalować i uruchomić system BPP. Wszystkie pozostałe tematy — konfiguracja, monitoring, backupy, upgrade PostgreSQL, przenosiny serwera, rozwiązywanie problemów — opisuje pełna dokumentacja.

Wymagania sprzętowe

Zasób	Minimum	Zalecane
RAM	12 GB	16 GB+
CPU	2 rdzenie	4+ rdzeni
Dysk	20 GB + miejsce na bazę i backupy	SSD

Przy 12 GB cały stack się mieści, ale ciasno (baza danych na minimum). Dopiero od 16 GB nadwyżka RAM realnie zasila bazę, aplikację i workery. Podczas pierwszego uruchomienia make configure-resources dobiera limity RAM/CPU per usługa pod wykryty host i ostrzega, jeśli host ma poniżej 12 GB. Szczegóły modelu limitów: Limity zasobów.

Jak zainstalować i uruchomić system BPP przy pomocy bpp-deploy

Wybierz swój system operacyjny. 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

Linux

Otwórz Terminal (zazwyczaj skrót Ctrl+Alt+T lub znajdziesz go w menu aplikacji).

Debian / Ubuntu

sudo apt update
sudo apt install -y git make openssl

Zainstaluj Docker Engine — oficjalna instrukcja dla Debian lub Ubuntu (zawiera Docker Compose).

Podpowiedź: Możesz też zainstalować Docker poleceniem make install-docker po sklonowaniu repo (Debian/Ubuntu — używa apt i oficjalnego repozytorium Dockera).

Fedora

sudo dnf install -y git make openssl

Zainstaluj Docker Engine — oficjalna instrukcja dla Fedory (zawiera Docker Compose).

Arch Linux

sudo pacman -Sy --noconfirm git make openssl
sudo pacman -Sy --noconfirm docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Wyloguj się i zaloguj ponownie, aby uprawnienia do Dockera zaczęły działać.

openSUSE

sudo zypper install -y git make openssl

Zainstaluj Docker Engine — oficjalna instrukcja dla SLES/openSUSE (zawiera Docker Compose).

Dodaj użytkownika do grupy docker, żeby make i docker compose działały bez sudo:

sudo usermod -aG docker $USER

Wyloguj się i zaloguj ponownie, aby zmiana zaczęła obowiązywać (lub newgrp docker w bieżącym terminalu). Sprawdź: docker run --rm hello-world powinno wykonać się bez sudo.

Uwaga bezpieczeństwa: członkostwo w grupie docker jest równoważne uprawnieniom roota na hoście. Dodawaj do niej tylko zaufane konta administratorów.

Sklonuj repozytorium:

git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deploy

Więcej: dokumentacja → Instalacja → Linux.

macOS

Otwórz Terminal (Spotlight: Cmd+Spacja, wpisz „Terminal").

xcode-select --install      # git + make (potwierdź w oknie dialogowym)

Zainstaluj Docker Desktop dla macOS (wybierz Apple Silicon dla M1/M2/M3/M4 lub Intel), uruchom i poczekaj, aż ikona w pasku menu przestanie się animować.

Sklonuj repozytorium:

git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deploy

Więcej: dokumentacja → Instalacja → macOS.

Windows

Najprościej: przez WSL2. To wbudowany w Windows podsystem Linuksa. Aby uruchomić BPP na Windows, potrzebujesz zainstalować Docker Desktop, który i tak z niego korzysta.

1. Włącz WSL2. Kliknij prawym przyciskiem na przycisk Start, wybierz Terminal (Administrator) (na Windows 10: Windows PowerShell (Administrator)), wpisz wsl --install i zrestartuj komputer. Komenda włącza WSL2 i instaluje Ubuntu; jeśli WSL jest już włączony, po prostu to zgłosi. Wymagany jest Windows 11 albo Windows 10 w wersji 2004 (build 19041) lub nowszej, z włączoną wirtualizacją w BIOS/UEFI — dokładnie te same wymagania, co Docker Desktop.

2. Zainstaluj Docker Desktop. Otwórz PowerShell — naciśnij klawisz Windows, zacznij pisać powershell i kliknij aplikację Windows PowerShell:

winget install -e --id Docker.DockerDesktop --source winget

Uruchom Docker Desktop i poczekaj, aż ikona wieloryba w zasobniku przestanie się animować. Następnie w Settings → Resources → WSL Integration włącz suwak przy dystrybucji Ubuntu — dzięki temu docker i docker compose zadziałają wprost w Ubuntu, korzystając z tego samego silnika.

3. Otwórz Ubuntu. Kliknij w pasek wyszukiwania obok przycisku Start (albo naciśnij klawisz Windows), wpisz ubuntu i kliknij aplikację:

Przy pierwszym uruchomieniu Ubuntu poprosi o nazwę użytkownika i hasło — to konto wewnątrz Linuksa, niezależne od konta Windows.

4. Zainstaluj narzędzia i sklonuj repozytorium. Od tego momentu instalacja przebiega dokładnie tak, jak na Linuksie — bo to jest Linux:

sudo apt update && sudo apt install -y git make openssl
cd ~
git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deploy

Ważne: trzymaj repozytorium w systemie plików Linuksa. Nie klonuj go do /mnt/c/…, czyli na dysk C:, pulpit ani do Dokumentów — na granicy systemów plików Windows i Linuksa kontenery działają bardzo wolno, a uprawnienia plików nie przenoszą się poprawnie. Do plików zajrzysz z Eksploratora: wpisz w Ubuntu explorer.exe . albo otwórz ścieżkę \\wsl$\Ubuntu\home.

Wolę zostać po stronie Windows — instalacja przez Git Bash

Ta ścieżka też wymaga WSL2 — Docker Desktop bez niego nie działa, więc krok 1 powyżej wykonaj również tutaj. Różnica polega na tym, że make uruchamiasz w Git Bashu po stronie Windows, a nie w Ubuntu.

Otwórz PowerShell (klawisz Windows → „powershell") i zainstaluj komplet narzędzi:

winget install -e --id Git.Git --source winget
winget install -e --id Docker.DockerDesktop --source winget
winget install -e --id ezwinports.make --source winget

Dostajesz Git Bash z narzędziami Unix (bash, sed, openssl), Docker Engine z Docker Compose oraz GNU Make 4.4. winget jest wbudowany w Windows 11 i w Windows 10 od wersji 1809 (build 17763); sprawdź winget --version, a jeśli go brak — doinstaluj Instalator aplikacji ze Sklepu Microsoft.

Podpowiedź: Jeśli masz już Gita i make, a brakuje tylko Dockera — po sklonowaniu repo uruchom w Git Bash make install-docker. Zainstaluje Docker Desktop przez winget, a jeśli wingeta nie ma — odeśle do Instalatora aplikacji w Sklepie Microsoft.

Bez wingeta (Windows 10 starszy niż 1809, zablokowany Sklep): pobierz i zainstaluj ręcznie Git for Windows oraz Docker Desktop for Windows. GNU Make nie wymaga menedżera pakietów — to pojedynczy, samowystarczalny plik. Pobierz make-4.4.1-without-guile-w32-bin.zip (392 KB, projekt ezwinports — ten sam plik, który instaluje winget), rozpakuj i skopiuj bin\make.exe do C:\Program Files\Git\usr\bin\ (Windows poprosi o potwierdzenie administratora). Ten katalog jest już w PATH Git Basha, a make.exe importuje wyłącznie systemowe biblioteki Windows, więc wystarczy ten jeden plik. Jeśli i tak masz już Chocolatey albo Scoop — wystarczy choco install make (PowerShell jako Administrator) lub scoop install make.

Uruchom Docker Desktop i poczekaj, aż ikona wieloryba w zasobniku przestanie się animować.

Otwórz nowe okno Git Bash — kliknij w pasek wyszukiwania obok przycisku Start (albo naciśnij klawisz Windows), wpisz git bash i kliknij aplikację, którą poznasz po kolorowym rombie:

Git Bash startuje w katalogu domowym użytkownika, więc sklonuj repozytorium na pulpit — dzięki temu katalog bpp-deploy będziesz mieć zawsze pod ręką:

cd Desktop
git clone https://github.com/iplweb/bpp-deploy.git
cd bpp-deploy

Na dysku katalog pulpitu nazywa się Desktop także w polskiej wersji Windows. Jeśli cd Desktop zgłosi brak katalogu, pulpit przejął OneDrive — wpisz wtedy cd OneDrive/Desktop albo cd OneDrive/Pulpit.

Ważne: Od tego momentu wszystkie komendy make uruchamiaj w Git Bash, nie w CMD ani PowerShell. Musi to być okno otwarte po instalacji — dopiero nowo uruchomiony terminal widzi make dopisany do PATH przez winget.

Więcej: dokumentacja → Instalacja → Windows.

Wspólne kroki konfiguracji

Poniższe kroki wykonujesz po zakończeniu instrukcji właściwych dla Twojego systemu operacyjnego. Są identyczne dla Linux, macOS i Windows.

1. Pierwsze uruchomienie

make

Przy pierwszym uruchomieniu make zapyta o ścieżkę do katalogu konfiguracyjnego (musi znajdować się poza repozytorium — jego nazwa stanie się nazwą projektu Docker Compose; pod Windows możesz podać ścieżkę windowsową, np. C:\dane\bpp) i automatycznie: utworzy strukturę katalogów, skopiuje szablony z defaults/, wygeneruje losowe hasła i utworzy plik .env.

2. Sprawdź i dostosuj konfigurację

Otwórz .env z katalogu konfiguracyjnego (ścieżka wyświetli się po pierwszym make, np. /home/deploy/moja-instancja/.env) i ustaw:

• DJANGO_BPP_HOSTNAME — nazwę hosta (np. publikacje.uczelnia.pl)
• DJANGO_BPP_CSRF_EXTRA_ORIGINS — dozwolone originy CSRF

Dodaj certyfikaty SSL:

# Opcja A: własne certyfikaty — skopiuj cert.pem i key.pem do podkatalogu ssl/
# Opcja B: samopodpisane (snakeoil) do testów:
make generate-snakeoil-certs
# Opcja C: Let's Encrypt (DNS musi wskazywać na serwer, port 80 osiągalny):
make ssl-letsencrypt-issue           # staging - test pipeline'u
make ssl-letsencrypt-issue PROD=1    # prawdziwy cert + flip mode na 'letsencrypt'

Szczegóły SSL, multi-host i limitów zasobów: dokumentacja → Konfiguracja.

3. Uruchom usługi

make run

4. Otwórz aplikację w przeglądarce

Główny serwis jest dostępny przez webserver (Nginx) na portach 80 i 443. Otwórz aplikację pod adresem hosta zgodnym z DJANGO_BPP_HOSTNAME (lokalnie najprościej DJANGO_BPP_HOSTNAME=localhost → https://localhost/).

Przy pustej bazie aplikacja przekieruje do /setup/ — kreatora, w którym tworzysz pierwsze konto administratora.

Narzędzia administracyjne i monitoring są dostępne przez Nginx (chronione uwierzytelnianiem): https://<hostname>/grafana/, /netdata/, /flower/, /dozzle/.

Dokumentacja

Pełna dokumentacja: iplweb.github.io/bpp-deploy

Sekcja	Tematy
Instalacja	Linux / macOS / Windows, pierwsze uruchomienie
Konfiguracja	architektura, SSL, multi-host, limity zasobów, PostgreSQL
Eksploatacja	komendy make, baza danych, backupy, przenosiny serwera, wydania
Monitoring i logi	Netdata, Loki, Grafana, alerty ntfy, wolne zapytania
Architektura	usługi, przepływ danych, healthchecks, zadania Ofelii
Rozwiązywanie problemów	najczęstsze problemy przy starcie
Rozwój pakietu	testy, pre-commit, backwards compatibility

Podgląd dokumentacji lokalnie:

pip install -r docs/requirements.txt
mkdocs serve   # http://127.0.0.1:8000

Licencja

MIT