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.

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 gettext

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 gettext

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

Arch Linux

sudo pacman -Sy --noconfirm git make openssl gettext
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 gettext-runtime

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)
brew install gettext        # envsubst (wymaga Homebrew: https://brew.sh/)

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

Pobierz i zainstaluj:

• Git for Windows — dostarcza Git Bash
• Docker Desktop for Windows — uruchom i poczekaj, aż ikona w zasobniku przestanie się animować

W PowerShell jako Administrator zainstaluj GNU Make (Chocolatey lub Scoop):

choco install make

Otwórz Git Bash i sklonuj repozytorium:

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

Ważne: Od tego momentu wszystkie komendy make uruchamiaj w Git Bash, nie w CMD ani PowerShell.

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