ansible-openwisp-wifi-login-pages

Rola Ansible do wdrożenia i zarządzania openwisp-wifi-login-pages.

Wymagane zmienne:

• wifi_login_pages_domains: lista z nazwą hosta, pod którym aplikacja będzie dostępna.
• wifi_login_pages_organizations_src: lokalna ścieżka do katalogu zawierającego konfigurację organizacji.

Użytkowanie (samouczek)

Jeśli nie wiesz, jak używać Ansible, nie panikuj, ta procedura poprowadzi Cię do pełnej, działającej podstawowej instalacji openwisp-wifi-login-pages.

Jeśli już znasz Ansible, możesz pominąć ten samouczek.

Przede wszystkim musisz zrozumieć dwa kluczowe pojęcia:

• przez "serwer produkcyjny" rozumiemy serwer (nie laptop ani komputer stacjonarny!) z publicznym ipv4 / ipv6, który jest wykorzystywany do hostowania openwisp2.
• przez "lokalną maszynę" rozumiemy maszynę, z której uruchamiasz Ansible, np. twój własny laptop.

Ansible jest narzędziem do zarządzania konfiguracją, które działa poprzez łączenie się z serwerami produkcyjnymi za pomocą SSH, więc musisz zainstalować je i skonfigurować na maszynie, z której przeprowadzisz wdrożenie, a ta maszyna musi mieć możliwość łączenia się z serwerem produkcyjnym przez SSH.

Ansible będzie uruchamiany na Twojej lokalnej maszynie, a stamtąd połączy się z serwerem produkcyjnym, aby zainstalować openwisp-wifi-login-pages.

Instalacja Ansible

Zainstaluj Ansible (wersja 2.13 lub wyższa) na swojej lokalnej maszynie (nie na serwerze produkcyjnym!), jeśli jeszcze tego nie zrobiłeś.

Aby zainstalować Ansible, sugerujemy postępować zgodnie z oficjalnym przewodnikiem instalacji Ansible. Zaleca się instalację Ansible w wirtualnym środowisku, aby uniknąć problemów z zależnościami.

Upewnij się, że masz zainstalowaną poprawną wersję Jinja w swoim środowisku Python:

pip install Jinja>=2.11

Wybór katalogu roboczego

Wybierz katalog roboczy na swojej lokalnej maszynie, w którym umieścisz konfigurację openwisp-wifi-login-pages.

Będzie to przydatne, gdy będziesz musiał zaktualizować openwisp-wifi-login-pages.

Np.:

mkdir ~/openwisp-wifi-login-pages-ansible-playbook
cd ~/openwisp-wifi-login-pages-ansible-playbook

Umieszczenie tego katalogu roboczego pod kontrolą wersji to również bardzo dobry pomysł.

Instalacja roli Ansible z ansible-galaxy

ansible-galaxy install openwisp.wifi_login_pages

Utworzenie pliku inwentaryzacyjnego

Plik inwentaryzacyjny to miejsce, w którym definiowane są grupy serwerów. W naszym prostym przypadku możemy zdefiniować tylko jedną grupę, w której umieścimy tylko jeden serwer.

Utwórz nowy plik o nazwie hosts w katalogu roboczym na swojej lokalnej maszynie (katalog stworzony w poprzednim kroku) z następującą zawartością:

[openwisp-wifi-login-pages]
openwisp-wifi-login-pages.mydomain.com

Utworzenie pliku playbooka

Utwórz nowy plik playbooka playbook.yml na swojej lokalnej maszynie z następującą zawartością:

- hosts: openwisp-wifi-login-pages
  become: "{{ become | default('yes') }}"
  roles:
    - openwisp.wifi_login_pages
  vars:
    wifi_login_pages_domains: ["wifi.openwisp.org"]

Linia become: "{{ become | default('yes') }}" oznacza, że Ansible użyje programu sudo, aby uruchomić każde polecenie. Możesz usunąć tę linię, jeśli jej nie potrzebujesz (np. jeśli używasz użytkownika root na serwerze produkcyjnym).

Możesz zastąpić openwisp-wifi-login-pages w polu hosts nazwą swojego serwera produkcyjnego, jeśli chcesz.

wifi_login_pages_domains to jedyna wymagana zmienna. Jest to lista z nazwą hosta, pod którym aplikacja będzie dostępna.

Uruchomienie playbooka

Teraz nadszedł czas, aby wdrożyć openwisp-wifi-login-pages na serwerze produkcyjnym.

Uruchom playbook z lokalnej maszyny za pomocą:

ansible-playbook -i hosts playbook.yml -u <user> -k --become -K

Zamień <user> na nazwę użytkownika swojego serwera produkcyjnego.

Argument -k wymaga programu sshpass.

Możesz usunąć -k, --become i -K, jeśli twój publiczny klucz SSH jest zainstalowany na serwerze.

Wskazówki:

• Jeśli otrzymujesz błąd typu Authentication or permission failure, spróbuj użyć użytkownika root: ansible-playbook -i hosts playbook.yml -u root -k.
• Jeśli otrzymujesz błąd dotyczący dodawania odcisku palca hosta do pliku known_hosts, możesz po prostu połączyć się z hostem przez SSH i potwierdzić, gdy zostaniesz zapytany; potem możesz ponownie uruchomić ansible-playbook.

Wdrożenie konfiguracji organizacji i zasobów

Aby wdrożyć pliki konfiguracyjne YAML organizacji i ich powiązane zasoby statyczne (logo, CSS itd.), wykonaj następujące kroki:

Krok 1: Zmień katalog na katalog z plikiem playbook.

cd <path_to_playbook_file >

Krok 2: Utwórz katalog files.

mkdir files

Krok 3: Skopiuj wszystkie konfiguracje organizacji i zasoby z katalogu organizations do files/owlp_organizations.

cp -r <path_to_organizations_directory> files/owlp_organizations

Wdrożenie tłumaczeń

Aby wdrożyć normalne i niestandardowe tłumaczenia, skopiuj wszystkie tłumaczenia z katalogu i18n do files/owlp_i18n.

cp -r <path_to_i18n_directory> files/owlp_i18n

Teraz uruchom playbook, a pliki zostaną wysłane na zdalny serwer.

Wdrożenie niestandardowej zawartości statycznej

Aby wdrożyć niestandardową zawartość statyczną (pliki HTML, PDF itp.), dodaj całą statyczną zawartość do katalogu files/owlp_static. Pliki w katalogu owlp_static zostaną przesłane na zdalny katalog static podczas uruchamiania playbooka.

Jak uruchomić testy

Jeśli chcesz przyczynić się do ansible-openwisp-wifi-login-pages, powinieneś uruchomić testy w swoim środowisku deweloperskim, aby upewnić się, że Twoje zmiany niczego nie psują.

Aby to zrobić, wykonaj następujące kroki:

Krok 1: Sklonuj ansible-openwisp-wifi-login-pages

Sklonuj repozytorium:

git clone https://github.com/<your_fork>/ansible-openwisp-wifi-login-pages.git

Krok 2: Zainstaluj dockera

Jeśli jeszcze nie zainstalowałeś dockera, musisz go zainstalować (przykład dla systemów linux debian/ubuntu):

sudo apt-get install docker.io

Krok 3: Zainstaluj molekuły i zależności

pip install molecule[docker] yamllint ansible-lint docker

Krok 4: Pobierz obrazy dockera

docker pull geerlingguy/docker-ubuntu2404-ansible:latest
docker pull geerlingguy/docker-ubuntu2204-ansible:latest
docker pull geerlingguy/docker-ubuntu2004-ansible:latest
docker pull geerlingguy/docker-debian11-ansible:latest
docker pull geerlingguy/docker-debian12-ansible:latest

Krok 5: Zainstaluj zależności Ansible

ansible-galaxy collection install community.docker

Krok 6: Uruchom test molekuły

molecule test -s local

Jeśli nie pojawią się żadne komunikaty o błędach, oznacza to, że testy przebiegły pomyślnie bez błędów.

ProTip: Użyj molecule test --destroy=never, aby przyspieszyć kolejne uruchomienia testów.