ansible-openwisp-wifi-login-pages

Роль Ansible для развертывания и управления openwisp-wifi-login-pages.

Необходимые переменные:

• wifi_login_pages_domains: список с именами хостов, по которым будет доступно приложение.
• wifi_login_pages_organizations_src: локальный путь к каталогу с конфигурацией организаций.

Использование (учебник)

Если вы не знаете, как использовать Ansible, не паникуйте, эта процедура поможет вам установить openwisp-wifi-login-pages с нуля.

Если вы уже знаете, как использовать Ansible, вы можете пропустить этот учебник.

Прежде всего, нужно понять два ключевых понятия:

• под "производственным сервером" мы понимаем сервер (не ноутбук и не настольный компьютер!) с публичным ipv4/ipv6, который используется для размещения openwisp2.
• под "локальной машиной" мы понимаем хост, с которого вы запускаете Ansible, т.е. ваш собственный ноутбук.

Ansible — это инструмент управления конфигурацией, который подключается к производственным серверам по SSH, поэтому вам нужно установить и настроить его на машине, с которой вы будете развертывать приложение. Эта машина должна иметь возможность подключаться по SSH к производственному серверу.

Ansible будет запущен на вашей локальной машине, и с ее помощью он подключится к производственному серверу для установки openwisp-wifi-login-pages.

Установка Ansible

Установите Ansible (версия 2.13 или выше) на вашу локальную машину (не на производственный сервер!), если вы еще этого не сделали.

Для установки Ansible рекомендуется следовать официальному руководству по установке Ansible. Рекомендуется устанавливать Ansible через виртуальную среду, чтобы избежать проблем с зависимостями.

Пожалуйста, убедитесь, что у вас установлена правильная версия Jinja в вашей среде Python:

pip install Jinja>=2.11

Выберите рабочий каталог

Выберите рабочий каталог на вашей локальной машине, где вы будете хранить конфигурацию openwisp-wifi-login-pages.

Это будет полезно, когда вам нужно будет обновить openwisp-wifi-login-pages.

Например:

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

Хорошей идеей также будет поместить этот рабочий каталог под контроль версий.

Установка роли Ansible из ansible-galaxy

ansible-galaxy install openwisp.wifi_login_pages

Создание файла инвентаризации

Файл инвентаризации — это место, где определяются группы серверов. В нашем простом случае мы можем обойтись определением одной группы, в которую добавим один сервер.

Создайте новый файл с названием hosts в рабочем каталоге вашей локальной машины (в каталоге, созданном на предыдущем шаге) со следующим содержимым:

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

Создание файла плейбука

Создайте новый файл плейбука playbook.yml на вашей локальной машине со следующим содержимым:

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

Строка become: "{{ become | default('yes') }}" означает, что Ansible будет использовать программу sudo для выполнения каждой команды. Вы можете удалить эту строку, если она вам не нужна (например, если вы используете пользователя root на производственном сервере).

Вы можете заменить openwisp-wifi-login-pages в поле hosts на имя хоста вашего производственного сервера, если хотите.

Переменная wifi_login_pages_domains является единственной обязательной переменной. Это список с именами хостов, по которым будет доступно приложение.

Запуск плейбука

Теперь пришло время развернуть openwisp-wifi-login-pages на производственном сервере.

Запустите плейбук с вашей локальной машины с помощью:

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

Подставьте <user> с именем пользователя вашего производственного сервера.

Аргумент -k потребует программу sshpass.

Вы можете удалить -k, --become и -K, если ваш открытый SSH-ключ установлен на сервере.

Советы:

• Если у вас возникла ошибка типа Authentication or permission failure, попробуйте использовать root пользователя: ansible-playbook -i hosts playbook.yml -u root -k.
• Если у вас возникла ошибка при добавлении отпечатка хоста в файл known_hosts, вы можете просто подключиться к хосту по SSH и ответить "да", когда вас попросят. Затем вы сможете снова запустить ansible-playbook.

Развертывание конфигураций и ресурсов организаций

Для развертывания YAML конфигурационных файлов организаций и связанных с ними статических ресурсов (логотип, CSS и др.) выполните следующие шаги:

Шаг 1: Перейдите в каталог с файлом плейбука.

cd <path_to_playbook_file>

Шаг 2: Создайте каталог files.

mkdir files

Шаг 3: Скопируйте все конфигурации организаций и ресурсы из каталога organizations в каталог files/owlp_organizations.

cp -r <path_to_organizations_directory> files/owlp_organizations

Развертывание переводов

Для развертывания обычных и пользовательских переводов скопируйте все переводы из каталога i18n в каталог files/owlp_i18n.

cp -r <path_to_i18n_directory> files/owlp_i18n

Теперь запустите плейбук, и файлы будут загружены на удаленный сервер.

Развертывание пользовательского статического контента

Для развертывания пользовательского статического контента (HTML-файлы, PDF и т.д.) добавьте весь статический контент в каталог files/owlp_static. Файлы внутри owlp_static будут загружены в удаленный каталог static во время выполнения плейбука.

Как запустить тесты

Если вы хотите внести вклад в ansible-openwisp-wifi-login-pages, вам следует запустить тесты в своей среде разработки, чтобы убедиться, что ваши изменения ничего не ломают.

Для этого выполните следующие шаги:

Шаг 1: Клонируйте ansible-openwisp-wifi-login-pages.

Клонируйте репозиторий с помощью:

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

Шаг 2: Установите Docker.

Если вы еще не установили Docker, вам нужно установить его (пример для систем Linux Debian/Ubuntu):

sudo apt-get install docker.io

Шаг 3: Установите molecule и зависимости.

pip install molecule[docker] yamllint ansible-lint docker

Шаг 4: Загрузите изображения Docker.

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

Шаг 5: Установите зависимости Ansible.

ansible-galaxy collection install community.docker

Шаг 6: Запустите тест Molecule.

molecule test -s local

Если вы не получили сообщений об ошибках, значит, тесты прошли успешно без ошибок.

Профессиональный совет: Используйте molecule test --destroy=never, чтобы ускорить последующие запуски тестов.