ansible-openwisp-wifi-login-pages

This is an Ansible role used to set up and manage openwisp-wifi-login-pages.

Required Variables:

• wifi_login_pages_domains: a list of hostnames where the app will be available.
• wifi_login_pages_organizations_src: the local path of the directory containing organization configurations.

Usage (Guide)

If you are unfamiliar with Ansible, don’t worry! This guide will help you with a basic installation of openwisp-wifi-login-pages.

If you already know how to use Ansible, feel free to skip this guide.

Key Concepts:

• "Production server": This refers to a dedicated server (not your laptop or desktop) with a public IPv4 or IPv6 address that hosts openwisp.
• "Local machine": This is the computer you use to run Ansible, such as your laptop.

Ansible connects to production servers through SSH. You need to install Ansible and configure it on your local machine and it should be able to SSH into the production server.

How to Install Ansible

1. Install Ansible (version 2.13 or higher) on your local machine (not the production server).
2. We recommend following the official Ansible installation guide. It’s best to install Ansible in a virtual environment to avoid dependency issues.

Also, ensure you have the right version of Jinja installed in your Python environment:

pip install Jinja>=2.11

Set a Working Directory

Create a directory on your local machine to hold the configuration for openwisp-wifi-login-pages. This will help you manage updates in the future.

Example:

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

It’s a good idea to put this directory under version control.

Install Ansible Role from Ansible Galaxy

Run:

ansible-galaxy install openwisp.wifi_login_pages

Create an Inventory File

The inventory file lists groups of servers. In this simple case, we will define one group for one server.

Create a file called hosts in your working directory with the following content:

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

Create a Playbook File

Create a file named playbook.yml in your working directory with this content:

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

The line become: "{{ become | default('yes') }}" means Ansible will use sudo for commands. You can remove this if you are logged in as the root user on the production server.

You may change openwisp-wifi-login-pages in the hosts field to your server's hostname if necessary.

The wifi_login_pages_domains is the only required variable, which is a list of hostnames where the app will be available.

Run the Playbook

Now you'll deploy openwisp-wifi-login-pages to the production server.

Run the playbook from your local machine like this:

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

Replace <user> with your production server username.

The -k option prompts you for the SSH password.

You can omit -k, --become, and -K if your public SSH key is already on the server.

Tips:

• If you see an error like Authentication or permission failure, try running as the root user:

  ansible-playbook -i hosts playbook.yml -u root -k
  

• If there’s an error about adding the host's fingerprint to the known_hosts file, simply connect via SSH and accept when prompted. Then run the command again.

Deploy Organizational Configurations and Assets

To deploy organization YAML configuration files and related static assets (like logos or CSS), follow these steps:

Step 1: Change your directory to where the playbook file is located:

cd <path_to_playbook_file>

Step 2: Create a directory called files.

mkdir files

Step 3: Copy organization configurations and assets from the organizations directory to files/owlp_organizations.

cp -r <path_to_organizations_directory> files/owlp_organizations

Deploy Translations

To deploy standard and custom translations, copy all translation files from the i18n directory to files/owlp_i18n:

cp -r <path_to_i18n_directory> files/owlp_i18n

Now run the playbook, and the files will be uploaded to the server.

Deploying Custom Static Content

To deploy custom static content (like HTML files, PDFs, etc.), place all static content inside the files/owlp_static directory. The contents of owlp_static will be uploaded to the remote static directory during playbook execution.

How to Run Tests

If you want to contribute to ansible-openwisp-wifi-login-pages, you should run tests in your development environment to ensure nothing is broken.

Follow these steps:

Step 1: Clone the repository:

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

Step 2: Install Docker.

If you haven’t installed Docker yet, here’s how to do it for Debian/Ubuntu:

sudo apt-get install docker.io

Step 3: Install Molecule and its dependencies:

pip install molecule[docker] yamllint ansible-lint docker

Step 4: Download Docker images:

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

Step 5: Install Ansible dependencies:

ansible-galaxy collection install community.docker

Step 6: Run Molecule test:

molecule test -s local

If there are no error messages, the tests ran successfully.

ProTip: Use molecule test --destroy=never to speed up subsequent test runs.