Instalacja platformy

Instalacja polega na uzupełnieniu kilku wartości w plikach konfiguracyjnych paczki i uruchomieniu jednego playbooka Ansible ze stacji wdrożeniowej. Paczka o nic nie pyta w trakcie działania.

Zanim zaczniesz

Przejdź przez Przygotowanie środowiska i odhacz listę kontrolną z sekcji 8. Najczęstszą przyczyną nieudanego startu jest Python starszy niż 3.11 na stacji wdrożeniowej.

1. Pobranie paczki instalacyjnej

Paczki wszystkich wydań wraz z opisem zmian znajdziesz na stronie Historia wydań - do nowej instalacji pobierz aktualne wydanie, wskazane na górze tej strony.

Archiwum zabezpieczone hasłem

Paczka jest zaszyfrowana. Hasło do archiwum przesyłane jest osobnym mailem przez zespół Testto - patrz Dostęp do skryptów.

Niektóre programy nie obsługują tego typu szyfrowania

Standardowe unzip w systemach Linux/macOS potrafi rozpakować archiwum bez pytania o hasło, pomijając przy tym wszystkie pliki - zostają same puste katalogi. Jeśli tak się stanie, użyj programu obsługującego szyfrowanie AES (np. 7-Zip: 7z x paczka.zip).

2. Zawartość paczki

<katalog-paczki>/
├── ansible.cfg                     konfiguracja Ansible - nie wymaga zmian
├── README.md                       skrócona instrukcja
├── preflight.yml                   sprawdzenie konfiguracji, niczego nie zmienia
├── testto.yml                      playbook instalacyjny
├── collections/requirements.yml    lista kolekcji Ansible do zainstalowania
├── roles/                          role instalatora
├── vars/release.yml                wersja wydania - nie edytować
└── inventories/klient/
    ├── inventory.yml               adres serwera i użytkownik SSH
    ├── ssl/                        tu wgrywasz certyfikat i CA proxy
    └── group_vars/all/
        ├── all.yml                 konfiguracja instalacji
        └── vault.yml               komplet haseł instalacji

Nazwa katalogu

Katalog wewnątrz archiwum nosi nazwę nadaną przy budowaniu paczki dla Twojej instalacji - sprawdź ją po rozpakowaniu. Wszystkie polecenia w tej dokumentacji wykonujesz wewnątrz tego katalogu.

Katalog inventories/ to Twoja własność - zachowaj go

inventories/klient/ zawiera konfigurację i hasła Twojej instalacji. Przy aktualizacji do nowszego wydania wymieniasz całą resztę paczki, ale ten katalog przenosisz bez zmian. Zrób jego kopię w bezpiecznym miejscu zaraz po uzupełnieniu danych - patrz Aktualizacja platformy.

3. Uzupełnienie danych instalacji

W plikach konfiguracyjnych pozostawione zostały wartości DO_UZUPELNIENIA. Znajdziesz wszystkie jednym poleceniem:

grep -rn DO_UZUPELNIENIA inventories/

3.1. Pola do uzupełnienia

Zestaw pól zależy od wariantu paczki - poniżej wszystkie, jakie mogą wystąpić.

Pole	Plik	Opis
`ansible_host`	`inventory.yml`	adres IP lub FQDN serwera aplikacyjnego
`ansible_user`	`inventory.yml`	użytkownik SSH z prawem do `sudo`
`ansible_password`	`vault.yml`	hasło SSH
`main_domain_name`	`all.yml`	domena główna instalacji
`robot_account_login`	`vault.yml`	login konta technicznego do rejestru obrazów
`robot_account_password`	`vault.yml`	hasło konta technicznego do rejestru obrazów
`vault_client_ssl_p12_password`	`vault.yml`	hasło do pliku `.p12` z certyfikatem
`proxy_http_url`	`all.yml`	adres proxy - tylko w wariancie za proxy
`mail_relay_upstream`	`all.yml`	serwer poczty w formacie `host:port`
`mail_from`	`all.yml`	adres nadawcy powiadomień

Poczta może zostać na później

Pola mail_relay_upstream i mail_from nie blokują instalacji. Pozostawione puste powodują, że wiadomości czekają w kolejce; po uzupełnieniu i ponownym uruchomieniu playbooka zostaną wysłane.

3.2. Hasło do `sudo`

Instalator wykonuje wszystkie zadania na serwerze przez sudo. Jeżeli konto nie ma sudo bez hasła, dopisz jedną linię w inventories/klient/inventory.yml, pod ansible_ssh_pass - wcięcie musi się zgadzać co do spacji:

  hosts:
    testto:
      ansible_host: "10.20.30.40"
      ansible_user: "administrator"
      ansible_ssh_pass: "{{ ansible_password }}"
      ansible_become_password: "{{ ansible_password }}"   # <- ta linia

Jeżeli hasło do sudo jest inne niż hasło SSH, nie dopisuj nic w inventory.yml — zamiast tego dodaj osobny sekret w inventories/klient/group_vars/all/vault.yml:

ansible_password: "haslo-ssh"
ansible_become_password: "haslo-do-sudo"

3.3. Logowanie kluczem SSH zamiast hasła

Wariant zalecany: usuwa wymóg sshpass na stacji wdrożeniowej i eliminuje hasło SSH z pliku z sekretami.

ssh-copy-id uzytkownik@<adres-serwera>

Następnie w inventories/klient/inventory.yml zamień linię z hasłem na ścieżkę do klucza:

  hosts:
    testto:
      ansible_host: "10.20.30.40"
      ansible_user: "administrator"
      ansible_ssh_private_key_file: "~/.ssh/id_rsa"
      ansible_become_password: "{{ ansible_password }}"

Hasło do sudo nadal potrzebne

Klucz SSH nie zastępuje hasła do sudo. Jeżeli konto nie ma NOPASSWD, zostaw ansible_become_password i pozostaw odpowiadające mu hasło w vault.yml.

3.4. Certyfikat TLS i certyfikat CA proxy

Pliki wgrywasz do inventories/klient/ssl/:

Plik	Kiedy	Uwagi
certyfikat `.p12`	gdy używasz własnego certyfikatu	nazwa musi się zgadzać z `client_ssl_p12_file` w `all.yml`, hasło w `vault_client_ssl_p12_password`
`proxy-ca.crt`	gdy proxy rozszywa ruch HTTPS	format PEM - patrz Instalacja za proxy

4. Zaszyfrowanie pliku z hasłami

inventories/klient/group_vars/all/vault.yml jest jawnym tekstem i zawiera komplet haseł instalacji: konta bazy danych, administratora uwierzytelniania, sekrety klientów OAuth, brokera i magazynu plików.

Traktuj paczkę jak plik z hasłami

Zaszyfrowanie pliku teraz nie cofa tego, że hasła przeszły już kanałem dostawy - ale ogranicza dalszą ekspozycję. Zrób to, zanim paczka gdziekolwiek zostanie albo pójdzie dalej.

ansible-vault encrypt inventories/klient/group_vars/all/vault.yml

Od tego momentu do każdego uruchomienia playbooka dokładaj --ask-vault-pass albo --vault-password-file <plik>.

5. Przygotowanie środowiska Ansible

Wykonujesz to na stacji wdrożeniowej, w katalogu rozpakowanej paczki.

Użyj Pythona 3.11 lub nowszego

Na Rocky Linux 9 i RHEL 9 polecenie python3 uruchamia wersję 3.9, która nie obsłuży wymaganego ansible-core. Wywołaj interpreter po nazwie z numerem wersji — instalacja python3.12 jest opisana w Przygotowaniu środowiska, sekcja 2.3.

Stacja bez dostępu do internetu

Pomiń tę sekcję i użyj gotowej paczki środowiska - patrz Przygotowanie środowiska, sekcja 2.6.

python3.12 -m venv ~/.venvs/ansible-testto
~/.venvs/ansible-testto/bin/pip install --upgrade pip
~/.venvs/ansible-testto/bin/pip install "ansible==11.*" psycopg2-binary passlib
~/.venvs/ansible-testto/bin/ansible-galaxy collection install -r collections/requirements.yml

Sprawdź wynik - pierwsza linia musi pokazać core 2.18 lub nowszy:

~/.venvs/ansible-testto/bin/ansible --version

Stacja wdrożeniowa za proxy

Zmienne proxy i certyfikat CA trzeba ustawić przed utworzeniem środowiska — inaczej pip i ansible-galaxy przerwą na weryfikacji certyfikatu. Procedura: Instalacja za proxy, sekcja 2.

6. Weryfikacja połączenia z serwerem

Zanim uruchomisz instalację, sprawdź czy logowanie i sudo działają:

~/.venvs/ansible-testto/bin/ansible testto -m ping -b

Poprawny wynik zawiera "ping": "pong". Przełącznik -b wymusza sudo, więc błędne lub brakujące hasło do sudo wyjdzie tutaj, a nie w połowie instalacji.

Ostrzeżenie o nazwach grup jest nieszkodliwe

[WARNING]: Invalid characters were found in group names but not replaced

Dotyczy myślnika w nazwie grupy inwentarza. Grupa działa normalnie - nic z tego nie wynika i nie należy tego szukać razem z prawdziwym błędem.

7. Sprawdzenie konfiguracji przed instalacją

Playbook preflight.yml weryfikuje kompletność i spójność konfiguracji, niczego nie zmieniając na serwerze:

~/.venvs/ansible-testto/bin/ansible-playbook preflight.yml

Sprawdza m.in.: pozostawione znaczniki DO_UZUPELNIENIA, spójność ustawień certyfikatu, otwieralność pliku .p12 podanym hasłem, osiągalność proxy i zewnętrznej bazy danych, poprawność i datę ważności licencji oraz zakres wdrażanych usług.

Wynik ma dwa poziomy: BLOKER przerywa przebieg (bez tej wartości nie powstanie działająca instalacja) i OSTRZEŻENIE, przy którym instalacja ma sens, choć w ograniczonym zakresie - sztandarowy przypadek to nieuzupełniona poczta.

Uruchom to zawsze

Kilkanaście sekund tutaj oszczędza kilkanaście minut przebiegu przerwanego na literówce, z maszyną już zaktualizowaną i zrestartowaną.

8. Uruchomienie instalacji

~/.venvs/ansible-testto/bin/ansible-playbook testto.yml

Jeżeli plik z hasłami został zaszyfrowany (sekcja 4), dołóż --ask-vault-pass.

Playbook aktualizuje system operacyjny i restartuje serwer

Instalator wykonuje dnf update wszystkich pakietów systemu, a następnie restartuje maszynę i czeka na jej powrót.

Przydatne warianty:

Przełącznik	Działanie
`--check --diff`	przebieg próbny - pokazuje, co by się zmieniło, bez zmieniania
`--ask-vault-pass`	pyta o hasło do zaszyfrowanego `vault.yml`
`--vault-password-file <plik>`	czyta hasło z pliku zamiast pytać

Nie edytuj vars/release.yml

Plik określa wersję wydania. Zmiana wersji obrazów odbywa się przez pobranie nowszej paczki - patrz Aktualizacja platformy

9. Weryfikacja po instalacji

Logowanie do aplikacji - otwórz https://dashboard.<domena> (lub z uzgodnionym prefiksem) i zaloguj się kontem administratora z pliku z hasłami.

Panele administracyjne są widoczne pod tą samą domeną

Poza aplikacją i logowaniem pod adresami *.<domena> na porcie 443 stają cztery panele administracyjne (podgląd logów, API i konsola magazynu plików, panel brokera). Chroni je wyłącznie hasło z pliku z hasłami. Jeżeli instalacja stoi w publicznym internecie, rozważ ograniczenie dostępu do nich po swojej stronie - na zaporze, VPN-ie albo reverse proxy. Aplikacja działa bez nich; są potrzebne wyłącznie do administracji.

Po udanej instalacji przejdź do Widoku głównego i projektów oraz Zarządzania użytkownikami.