ansible-openwisp-wifi-login-pages

Rôle Ansible pour déployer et gérer openwisp-wifi-login-pages.

Variables requises :

• wifi_login_pages_domains : une liste avec le nom d'hôte où l'application sera accessible.
• wifi_login_pages_organizations_src : chemin local du répertoire contenant la configuration des organisations.

Utilisation (tutoriel)

Si vous ne savez pas comment utiliser Ansible, pas de panique, cette procédure vous guidera vers une installation de base fonctionnelle d'openwisp-wifi-login-pages.

Si vous connaissez déjà Ansible, vous pouvez passer ce tutoriel.

Tout d'abord, vous devez comprendre deux concepts clés :

• Par « serveur de production », nous entendons un serveur (pas un ordinateur portable ou de bureau !) avec une adresse IPv4 / IPv6 publique utilisé pour héberger openwisp2.
• Par « machine locale », nous entendons l'hôte à partir duquel vous lancez Ansible, par exemple : votre propre ordinateur portable.

Ansible est un outil de gestion de configuration qui fonctionne en accédant aux serveurs de production via SSH, donc vous devez l'installer et le configurer sur la machine où vous lancez le déploiement et cette machine doit pouvoir se connecter en SSH au serveur de production.

Ansible sera exécuté sur votre machine locale et se connectera au serveur de production pour installer openwisp-wifi-login-pages.

Installer Ansible

Installez Ansible (version 2.13 ou supérieure) sur votre machine locale (pas sur le serveur de production !) si vous ne l'avez pas déjà fait.

Pour installer Ansible, nous vous recommandons de suivre le guide d'installation officiel d'Ansible. Il est recommandé d'installer Ansible dans un environnement virtuel pour éviter les problèmes de dépendance.

Veuillez vous assurer que vous avez la version correcte de Jinja installée dans votre environnement Python :

pip install Jinja>=2.11

Choisir un répertoire de travail

Choisissez un répertoire de travail sur votre machine locale où placer la configuration d'openwisp-wifi-login-pages.

Cela sera utile lorsque vous devrez mettre à jour openwisp-wifi-login-pages.

Exemple :

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

Placer ce répertoire de travail sous contrôle de version est également une très bonne idée.

Installer le rôle Ansible depuis ansible-galaxy

ansible-galaxy install openwisp.wifi_login_pages

Créer un fichier d'inventaire

Le fichier d'inventaire est l'endroit où les groupes de serveurs sont définis. Dans notre cas simple, nous pouvons nous contenter de définir un seul groupe dans lequel nous mettrons un seul serveur.

Créez un nouveau fichier appelé hosts dans le répertoire de travail de votre machine locale (le répertoire juste créé à l'étape précédente) avec le contenu suivant :

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

Créer un fichier de playbook

Créez un nouveau fichier de playbook playbook.yml sur votre machine locale avec le contenu suivant :

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

La ligne become: "{{ become | default('yes') }}" signifie qu'Ansible utilisera le programme sudo pour exécuter chaque commande. Vous pouvez supprimer cette ligne si vous n'en avez pas besoin (par exemple : si vous utilisez l'utilisateur root sur le serveur de production).

Vous pouvez remplacer openwisp-wifi-login-pages dans le champ hosts par le nom d'hôte de votre serveur de production si vous le souhaitez.

Le wifi_login_pages_domains est la seule variable requise. C'est une liste avec le nom d'hôte où l'application sera accessible.

Exécuter le playbook

Il est maintenant temps de déployer openwisp-wifi-login-pages sur le serveur de production.

Exécutez le playbook depuis votre machine locale avec :

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

Remplacez <user> par le nom d'utilisateur de votre serveur de production.

L'argument -k nécessitera le programme sshpass.

Vous pouvez supprimer -k, --become et -K si votre clé SSH publique est installée sur le serveur.

Conseils :

• Si vous obtenez une erreur telle que Échec de l'authentification ou permission, essayez d'utiliser l'utilisateur root ansible-playbook -i hosts playbook.yml -u root -k.
• Si vous voyez une erreur concernant l'ajout de l'empreinte de l'hôte au fichier known_hosts, vous pouvez simplement vous connecter à l'hôte via SSH et répondre oui quand on vous le demande ; ensuite, vous pourrez exécuter à nouveau ansible-playbook.

Déployer les configurations et ressources des organisations

Pour déployer les fichiers de configuration YAML des organisations et leurs ressources statiques associées (logo, CSS, etc.), procédez comme suit :

Étape 1 : Changez de répertoire vers le fichier playbook Ansible.

cd <chemin_vers_fichier_playbook>

Étape 2 : Créez le répertoire files.

mkdir files

Étape 3 : Copiez toutes les configurations des organisations et les ressources du répertoire organizations vers files/owlp_organizations.

cp -r <chemin_vers_repertoire_organizations> files/owlp_organizations

Déployer des traductions

Pour déployer des traductions normales et personnalisées, copiez toutes les traductions du répertoire i18n vers files/owlp_i18n.

cp -r <chemin_vers_repertoire_i18n> files/owlp_i18n

Maintenant, exécutez le playbook et les fichiers seront téléchargés à distance.

Déployer du contenu statique personnalisé

Pour déployer un contenu statique personnalisé (fichiers HTML, PDF, etc.), ajoutez tout le contenu statique dans le répertoire files/owlp_static. Les fichiers dans owlp_static seront téléchargés dans le répertoire static distant lors de l'exécution du playbook.

Comment exécuter les tests

Si vous souhaitez contribuer à ansible-openwisp-wifi-login-pages, vous devriez exécuter des tests dans votre environnement de développement pour vous assurer que vos modifications ne causent pas de problèmes.

Pour ce faire, suivez les étapes suivantes :

Étape 1 : Clonez ansible-openwisp-wifi-login-pages

Clonez le dépôt en :

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

Étape 2 : Installez Docker

Si vous n'avez pas encore installé Docker, vous devez l'installer (exemple pour les systèmes Linux Debian/Ubuntu) :

sudo apt-get install docker.io

Étape 3 : Installez Molecule et ses dépendances

pip install molecule[docker] yamllint ansible-lint docker

Étape 4 : Téléchargez les images 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

Étape 5 : Installez les dépendances Ansible

ansible-galaxy collection install community.docker

Étape 6 : Exécutez le test Molecule

molecule test -s local

Si vous ne obtenez aucun message d'erreur, cela signifie que les tests se sont bien déroulés sans erreurs.

Astuce Pro : Utilisez molecule test --destroy=never pour accélérer les exécutions de tests suivantes.