Instrukcja uruchomienia i przeprowadzenia webinaru

Dokument prowadzi krok po kroku od pustego środowiska do zakończonego webinaru z nagraniem i certyfikatami. Opisuje uruchomienie lokalne, na localhost, przeznaczone do testów przed wdrożeniem u klienta.

Co obejmuje ten dokument

Rozdziały 2-5 to przygotowanie środowiska, wykonywane raz. Rozdziały 6-10 to cykl życia pojedynczego webinaru, powtarzany przy każdym wydarzeniu. Rozdział 12 to gotowy scenariusz testu, rozdział 12 to katalog typowych problemów.

Czym jest ta platforma

Aplikacja obsługuje pełny cykl życia szkolenia online: rejestrację uczestnika, przypomnienia mailowe i SMS, spotkanie wideo, interakcje na żywo (czat, pytania, zapisy na zadania, zapytania ofertowe), nagranie, podsumowanie i certyfikaty uczestnictwa.

Model wdrożenia zakłada osobną instancję dla każdego klienta, na jego serwerze i jego domenie. Jedno repozytorium, jedna wersja kodu, a różnice między klientami wyłącznie w konfiguracji.

Mapa cyklu życia wydarzenia

Uruchomienie środowiska

Całość działa w Dockerze. Do testów lokalnych wystarczą cztery usługi, a wideo we własnym serwerze dokłada kolejne cztery.

Wymagania

Krok po kroku

# w katalogu Webinar-platform
cp .env.example .env

docker compose up -d --build

docker compose ps
curl http://localhost:8080/api/health

docker compose --profile livekit up -d

Adresy po uruchomieniu

Pierwsze logowanie

Konto administratora powstaje automatycznie przy pierwszym starcie backendu, na podstawie zmiennych z .env.

Otwórz panel

Wejdź na http://localhost:8081. Aplikacja przekieruje na ekran logowania pod /logowanie.

Zaloguj się danymi z .env

Login to wartość ADMIN_EMAIL, hasło to ADMIN_PASSWORD. Jeśli hasła nie podano, aplikacja wylosowała je i wypisała raz w logu przy pierwszym starcie:

docker compose logs backend | grep -i has

Zmień hasło, jeśli aplikacja o to poprosi

Konto z hasłem wygenerowanym automatycznie ma ustawioną flagę wymuszającą zmianę przy pierwszym logowaniu.

Co widzisz po zalogowaniu

Ekranem głównym panelu jest Podsumowanie pod adresem /. Pokazuje wyłącznie rzeczy, na które można zareagować: co się zbliża i co czeka na obsługę. Lewe menu ma następujące pozycje:

Konfiguracja instancji

Wszystko poza sekretami startowymi ustawia się w panelu, w /ustawienia. Zmiany działają natychmiast, bez restartu aplikacji.

Podstrony ustawień

Minimum do przeprowadzenia webinaru

Pole sekretne zachowuje się inaczej

Tryb bezpieczny wysyłki

Najważniejszy rozdział dla testów. Domyślnie włączony bezpiecznik kieruje całą pocztę i wszystkie SMS-y na jeden wskazany adres.

Jak to działa

Sprawdzenie stanu przed testem

Ustawienia zmieniają się przez panel, bez restartu aplikacji, więc wartość sprzed kilku minut może już nie obowiązywać. Przed każdym krokiem, który może wysłać wiadomość, sprawdź faktyczny stan w bazie:

docker exec webinar-postgres psql -U webinar -d webinar -c \
  "SELECT \"key\", value FROM app_settings
   WHERE \"key\" LIKE '%SAFE%' OR \"key\"='SMS_ENABLED';"

Co zapisuje dziennik

Wpis w tabeli notifications zachowuje prawdziwego odbiorcę, nie zastępczego. Dziennik dokumentuje zamiar wysyłki, więc po wyłączeniu trybu bezpiecznego nadal wiadomo, kto co miał dostać.

Przekroczenie limitu to nie błąd

Wiadomość ponad limit godzinowy dostaje status oczekującej, a nie nieudanej. Ma pójść, tylko później: zadanie w tle podejmie ją przy kolejnym przebiegu. Zaproszenie na całą bazę kontaktów to największy jednorazowy ruch w aplikacji, więc to tam bezpiecznik zadziała najczęściej.

Webinar testowy: komplet danych do wpisania

Wszystkie kolejne rozdziały pokazują jeden konkretny webinar: szkolenie o ocenie ryzyka i bezpieczeństwie wody po nowelizacji z 13 marca 2026 r. Ten rozdział zbiera wartości do wpisania, a następne pokazują je na zrzutach z działającej instancji.

Zakładka Podstawowe

Zakładka Termin

Zakładka Zapisy

Zakładka Treść strony

Treść buduje program szkolenia z materiału źródłowego. Struktura, która sprawdza się w praktyce: dla kogo, program, podstawa prawna, zastrzeżenie.

Zakładka Wideo

Zakładka Przypomnienia

Przy szkoleniu z terminem ustawowym harmonogram domyślny instancji jest wystarczający:

Dane uczestnika testowego

Materiał źródłowy

Treść merytoryczna pochodzi z opracowania „Plany bezpieczeństwa wody i ocena ryzyka - podstawy prawne, terminy i sankcje”, stan prawny na 27 sierpnia 2026 r. Kluczowe liczby, przydatne przy budowaniu zadań i tematów zapytań:

Utworzenie webinaru

Formularz jest podzielony na zakładki, ale zapis jest jeden. Przechodzenie między zakładkami nie gubi niezapisanych zmian.

Wejdź w Webinary i kliknij Nowy webinar (adres /webinary/nowy).

Podstawowe Treść strony Termin Zapisy Przypomnienia Pozostałe

Zakładka: Podstawowe

Pole	Wymagane	Opis
Tytuł	tak	Maksymalnie 255 znaków. Widoczny wszędzie: na stronie zapisu, w mailach, na certyfikacie
Adres strony zapisu	nie	Końcówka adresu po /w/. Podpowiadana z tytułu, dopóki jej nie dotkniesz. Konflikty rozstrzyga backend sufiksem liczbowym
Krótki opis	nie	Jedno, dwa zdania bez formatowania. Trafia do zajawki linku w komunikatorach i do treści maili

Przy adresie strony są przyciski Kopiuj oraz, w trybie edycji, Otwórz. Jeśli nie ustawiłeś adresu publicznego instancji, pojawi się tu ostrzeżenie.

Opis to nie treść strony. To dwie różne rzeczy: opis jest krótką zajawką, a treść strony to długi materiał z edytora. Nie zastępuj jednego drugim.

Zakładka: Treść strony

Edytor wizualny, w którym buduje się zawartość publicznej strony zapisu: nagłówki, listy, obrazki, linki i wyrównanie. Treść pojawia się nad formularzem zapisu. Pusta treść oznacza stronę z samym formularzem.

Obrazki wstawia się z biblioteki mediów. Trafiają do MinIO, a do treści wchodzi adres, nigdy dane w base64.

Treść jest czyszczona na backendzie przy każdym zapisie, według białej listy. Do bazy trafia wyłącznie wersja oczyszczona. Obrazek z obcego serwera jest usuwany, bo ujawniałby adresy IP odwiedzających właścicielowi obcego serwera.

Zakładka: Termin

Godziny podaje się w strefie webinaru, a nie w strefie przeglądarki. Strefa jest wypisana przy każdym polu.

Pole	Wymagane	Opis
Strefa czasowa	nie	Domyślnie Europe/Warsaw
Rozpoczęcie	tak	Data i godzina startu
Zakończenie	tak	Musi być późniejsze niż rozpoczęcie. Wyznacza moment startu automatów po webinarze

Do testu ustaw termin w przyszłości. Termin w przeszłości uruchamia zadanie podsumowań i zamyka zapisy. Jeśli chcesz od razu wejść do pokoju, patrz scenariusz w rozdziale 12.

Zakładka: Zapisy

Pole	Opis
Zapisy otwarte	Przełącznik, domyślnie włączony. To intencja, a nie stan faktyczny
Termin zapisów	Nie może być późniejszy niż początek webinaru. Puste oznacza brak terminu granicznego
Limit miejsc	Liczba całkowita, minimum 1. Puste oznacza brak limitu
Link do spotkania	Wysyłany w mailu potwierdzającym. Nie jest pokazywany publicznie. Wypełniany ręcznie w trybie NONE

Przełącznik „zapisy otwarte” to intencja, a nie stan faktyczny. Aplikacja nigdy nie zmienia go sama. Rzeczywistą dostępność wylicza z intencji, terminu, limitu miejsc i statusu, dzięki czemu po rezygnacji uczestnika zapisy wracają do stanu ustawionego przez Ciebie, zamiast otwierać się same.

Limit miejsc jest pilnowany pod blokadą wiersza w bazie. Kilkadziesiąt równoczesnych zapisów na dziesięć miejsc skończy się dokładnie dziesięcioma wpisami.

Zakładka: Przypomnienia

Lista reguł, każda z odstępem przed startem i kanałem. Nowy webinar dostaje harmonogram domyślny z ustawień instancji, a tu można go zmienić dla konkretnego wydarzenia.

Odstęp wybiera się z gotowych wartości albo podaje własny w dniach, godzinach lub minutach. Pod spodem widać skutek zwykłym zdaniem, na przykład „Zostanie dodane przypomnienie 7 dni przed, wysyłane przez e-mail”.

SMS wymaga zgody marketingowej i numeru telefonu. Uczestnik bez zgody dostanie tylko przypomnienia mailowe. Treść SMS jest celowo bez polskich znaków: ogonki przełączają bramkę na kodowanie, w którym limit spada ze 160 do 70 znaków i jedna wiadomość rozbija się na kilka płatnych części.

Przypomnienie spóźnione bardziej niż okno tolerancji (domyślnie 30 minut) nie idzie w ogóle. Chroni to przed lawiną wysyłek wstecz po restarcie aplikacji.

Pozostałe zakładki

Wideo - wybór dostawcy dla tego webinaru, zakładanie pokoju i lista prelegentów. Opisane w rozdziale 8.

Nagrania i materiały - wgrywanie plików do własnego składu, z ustawieniem widoczności.

Po webinarze - adresy nagrania i materiałów, gdy pliki leżą poza systemem (dysk sieciowy, YouTube), oraz przycisk Wyślij powiadomienie o nagraniu.

Przycisk powiadomienia działa na zapisanym adresie nagrania, a nie na treści pola. Inaczej powiadomienie niosłoby link sprzed edycji.

Walidacja

Formularz sprawdza dane przed wysłaniem i pokazuje zbiorczy komunikat „Formularz zawiera błędy”. Reguły:

• tytuł nie może być pusty,
• oba terminy są wymagane, a zakończenie musi być późniejsze niż rozpoczęcie,
• termin zapisów nie może być późniejszy niż początek webinaru,
• limit miejsc musi być liczbą dodatnią.

Zapis i status

Po zapisaniu webinar ma status DRAFT. Nie jest widoczny publicznie: strona zapisu zwraca 404, a zajawka dla robotów też go nie pokaże. To stan roboczy, w którym można spokojnie dopracować treść.

Wideo i prelegenci

Platforma nie jest przywiązana do jednego dostawcy wideo. Wybór jest świadomą decyzją, bo dostawcy różnią się tym, czy uprawnienia są egzekwowane, czy jedynie deklarowane.

Co gwarantuje który dostawca

Trzy role w pokoju

Założenie pokoju

Podniesienie głosu zapisanemu uczestnikowi

Poza prelegentami można nadać prawo głosu osobie, która zapisała się normalnie. Służy do tego kolumna Głos na liście zapisanych. Taki uczestnik dostaje prawo publikacji wyłącznie dźwięku: uprawnienia moderatora ma tylko prelegent wchodzący własnym linkiem.

Dwie kolumny dostawcy, nie jedna

Webinar pamięta dwie różne rzeczy: kto ma go obsługiwać (wybór administratora) i u kogo pokój faktycznie stoi (stan zapisany przez aplikację). Rozbieżność między nimi nie jest błędem, tylko sygnałem: „zmieniono dostawcę, pokój wciąż stoi u poprzedniego”. Panel pyta wtedy o potwierdzenie i zamyka stary pokój.

Publikacja i zapisy

Publikacja otwiera stronę zapisu dla świata. Do tego momentu wydarzenie jest niewidoczne.

Statusy webinaru

Warunki publikacji

Przycisk publikacji jest w wierszu listy webinarów, widoczny dopóki wydarzenie nie jest opublikowane ani odwołane. Publikacja przechodzi tylko wtedy, gdy webinar ma:

• niepusty tytuł,
• niepusty adres strony zapisu,
• oba terminy uzupełnione,
• status inny niż odwołany - webinaru odwołanego nie da się opublikować ponownie.

Karta webinaru

Karta pod /webinary/{id} zbiera wszystko, co należy do jednego wydarzenia, w ośmiu zakładkach:

Zapis uczestnika

Uczestnik podaje dane, zaznacza zgody i wysyła formularz. Po zapisie dostaje mail z potwierdzeniem, załącznikiem kalendarza invite.ics i linkiem do własnego zapisu pod /zapis/{token}, gdzie może sprawdzić szczegóły albo zrezygnować.

Rezygnacja z udziału jest możliwa ze strony własnego zapisu. Ponowny zapis po rezygnacji jest dozwolony, a zakolejkowane przypomnienia są przy rezygnacji kasowane.

Zaproszenia z bazy kontaktów

Poza publiczną stroną zapisu można zaprosić kontakty z bazy. Zakładka Zaproszenia pozwala wybrać grupy, zobaczyć podgląd liczby odbiorców po odfiltrowaniu wypisanych, osób bez zgody i już zaproszonych, a potem wysłać.

Przeprowadzenie webinaru

W dniu wydarzenia pracujesz na dwóch ekranach: sali spotkania i panelu prowadzenia. Uczestnik ma jeden ekran, na którym ma wszystko.

Okno czasowe pokoju

Ekran uczestnika

Adres /spotkanie/{token} jest wspólny dla uczestnika i prelegenta: strona sama rozpoznaje, kto wchodzi, więc organizator nie musi pamiętać, który link komu wysłał.

Pasek akcji uczestnika

Cztery zakładki panelu uczestnika

Panel prowadzenia

Adres /webinary/{id}/prowadzenie, wejście ikoną w wierszu listy. Nagłówek pokazuje stan połączenia i ma przełącznik sygnału dźwiękowego. Poniżej cztery kolumny, każda to niezależny strumień pracy:

Gdy przyjdzie nowe zapytanie ofertowe, na górze panelu pojawia się baner z odnośnikiem do listy zapytań. Jest też sygnał dźwiękowy, domyślnie włączony: to zgłoszenie, którego prowadzący najbardziej nie chce przegapić, a w trakcie mówienia nie patrzy na ekran.

Tryb otwartego mikrofonu

Przełącznik pozwala mówić każdemu bez proszenia o głos. Domyślnie wyłączony i to jest świadome: otwarty mikrofon na webinarze dla stu osób oznacza sto otwartych mikrofonów naraz. Ma sens przy warsztacie dla kilkunastu osób.

Wideo pozostaje wyłączone także w tym trybie: otwarty mikrofon nie włącza nikomu kamery.

Obecność

Obecność liczy się z sesji, a nie z flagi. Ludzie wchodzą i wychodzą, tracą połączenie, wracają z telefonu; dopiero suma sesji mówi, ile ktoś naprawdę był obecny, i pozwala narysować wykres obecności w czasie.

Przeglądarka wysyła sygnał co minutę istniejącym już połączeniem, więc działa to także w trybie NONE, gdzie żadnego dostawcy nie ma. Sesje porzucone - zamknięta karta bez wylogowania - domyka zadanie w tle, przyjmując jako koniec ostatni sygnał, a nie chwilę zamknięcia.

Po webinarze

Część dzieje się sama, część wymaga decyzji organizatora.

Co dzieje się automatycznie

Godzinę po zakończeniu (wartość SUMMARY_DELAY_MINUTES) zadanie w tle kolejkuje maile: uczestnikom podziękowanie z listą zadań i linkami, prowadzącemu zestawienie.

Zestawienie dla prowadzącego zawiera dane kontaktowe, więc idzie wyłącznie na adresy wpisane w ustawieniach, nigdy na adres wzięty z formularza.

Nagranie

Certyfikaty

Zakładka Certyfikaty na karcie webinaru. Można wydać dokument pojedynczej osobie albo wszystkim naraz.

Weryfikacja publiczna pod /certyfikat/{numer} zwraca minimum: numer, tytuł, datę, imię z pierwszą literą nazwiska i informację o ważności. Endpoint jest otwarty dla całego internetu, więc nigdy nie pokazuje adresu e-mail, pełnego nazwiska ani linku do pliku.

Statystyki

Zakładka Statystyki pokazuje liczby zapisów i obecnych, wykres obecności w czasie, aktywność na czacie oraz skuteczność banerów i zaproszeń. Wszystko liczone w bazie, zapytaniami agregującymi.

Wykres obecności kończy się na chwili bieżącej, gdy webinar jeszcze trwa: rysowanie do przyszłego końca dawałoby długą linię zer. Skuteczność zaproszeń liczy się po wysłanych, nie po zakolejkowanych: zaproszenie, które nie wyszło, nie miało szansy przynieść zapisu.

Eksport listy zapisanych

Na liście zapisanych jest eksport CSV. Obejmuje wszystkich zapisanych, a nie bieżącą stronę, i zawiera czas obecności oraz wersję i datę zgody. Flaga obecności jest przy okazji przeliczana, żeby liczba na ekranie nie rozjechała się z kolumną w pliku.

Kopiowanie webinaru

Przy szkoleniach cyklicznych najczęstszą czynnością jest skopiowanie istniejącego wydarzenia ikoną kopiowania w wierszu listy.

Usunięcie webinaru

Scenariusz testowy na localhost

Gotowa ścieżka, która przechodzi przez wszystkie mechanizmy w jednym posiedzeniu, w około 30 minut.

Przygotowanie

• Kontenery działają: docker compose ps pokazuje usługi jako Up
• curl http://localhost:8080/api/health zwraca UP
• Profil wideo uruchomiony, jeśli testujesz spotkanie: docker compose --profile livekit up -d
• Adres publiczny instancji ustawiony na http://localhost:8081
• Poczta skonfigurowana i test wysyłki przechodzi
• Tryb bezpieczny włączony, adres i numer zastępczy uzupełnione

Przebieg

Lista kontrolna testu

• Strona zapisu widoczna dopiero po publikacji
• Mail potwierdzający z załącznikiem kalendarza
• Powtórny zapis daje identyczny ekran
• Przedpokój pokazuje imię z zapisu do potwierdzenia
• Prelegent publikuje obraz, uczestnik tylko odbiera
• Czat, pytania i głosowanie działają w obie strony
• Kolejka głosu otwiera i zamyka mikrofon
• Otwarty mikrofon nie kasuje kolejki
• Zadanie ogłoszone w panelu widoczne u uczestnika
• Zapytanie ofertowe trafia na listę i daje sygnał dźwiękowy
• Obecność i wykres w statystykach
• Podsumowanie po zakończeniu, dokładnie raz
• Nagranie dostępne dla zapisanych, niedostępne bez tokenu
• Certyfikat z poprawnymi polskimi znakami i działającą weryfikacją
• Kopia bez zapisów, z terminem zastępczym

Rozwiązywanie problemów

Katalog objawów, które przy tej architekturze pojawiają się najczęściej, wraz z rzeczywistą przyczyną.

Przydatne polecenia

# logi backendu na żywo
docker compose logs -f backend

# stan kontenerów
docker compose ps

# restart pojedynczej usługi
docker compose restart backend

# zatrzymanie całości, dane w wolumenach zostają
docker compose down

# dziennik powiadomień: co i do kogo poszło
docker exec webinar-postgres psql -U webinar -d webinar -c \
  "SELECT created_at, template, recipient, status FROM notifications
   ORDER BY created_at DESC LIMIT 20;"