1. How to use ansible¶
Prerequisites
Here is the list of Linux Distributions compatibles with the installation of Aero-Webb 7.6 software by using Ansible. They should already be installed using their respective installation documentation:
- Debian 11 or Higher
- Ubuntu 22.04 LTS or Higher
- Red Hat Enterprise Linux 8 or Higher
- AlmaLinux 8 or Higher
In order to use Ansible, you will need one of those Operating Systems:
- Any Linux Distribution with Python, Pip and Ansible installed on it
- Windows 10 or Superior with WSL activated and Python, Pip and Ansible installed into the WSL
These packages need to be installed in order to use playbooks :
- Python 2.7 or higher
- Ansible 2.10 or higher
- Pip 20.3 or higher
If you don’t know which Linux Distribution is installed on your server, you can type the following command line:
Here is an example of the result when we try this command line on a Debian 11 server:
1.1 Preparing Ansible¶
1.1.1 Inventory file¶
Before launching a playbook, you need to create an inventory file. This file must contain the name and IP address of your target.
Here is an example:
Here, [debian] is the name we gave to our destination server, and below it, the IPv4 address of this server.
1.1.2 Available Playbooks¶
There are two playbooks for Debian-based distributions, and two playbooks for Red Hat-based distributions, you will find them in Ansible/playbooks directory.
For each distribution, there is one playbook to install Aero-Webb and all of its dependencies from scratch, and another one to update Aero-Webb.
1.1.3 Setting up a Playbook¶
The first line of the playbook contains the targeted server’s name which had been set up into the Inventory file.
There is also a section with all environment variables we can modify, here is an example:
- hosts: debian #the machine we named in our inventory file
become: true #we need administrator privileges in this machine and change users
vars:
- url: [INSTANCE URL]
- archive: [ARCHIVE NAME WITHOUT .zip EXTENSION]
- archivePath: [PATH TO LOCAL AEROWEBB ARCHIVE]
- backup: [DATABASE BACKUP]
- pgPassword: [POSTGRESQL PASSWORD]
- dbPassword: [DATABASE PASSWORD]
tasks:
# some tasks
1.1.4 Ansible.cfg file¶
In your Ansible playbook directory, you will find the following file: ansible.cfg. It allows Ansible to change the user on the server during the execution of the playbook. Also, on Windows Subsystem for Linux (WSL), you will need to activate this file manually (it is not mandatory on Linux) in order to ensure a good execution of the playbook.
1.1.5 SSH connection¶
Before executing an Ansible playbook, you need to be sure that the computer you will use is able to connect by SSH to the targeted machine.
1.2 Executing a playbook¶
In the terminal, in order to execute your playbook, you will need to execute the following command line:
ansible-playbook -K --ask-pass [PATH_TO_ANSIBLE_REPERTORY]/playbooks/installAeroWebbDebian.yml -i [PATH_TO_ANSIBLE_REPERTORY]/inventory –u [TARGET_USER]
| Command | Explanation |
|---|---|
| ansible-playbook | it is the name of the command for executing a playbook. |
| -K | it is the option which let you enter the target server root password, you will need it in order to install Aero-Webb and the needed softwares |
| --ask-pass | this option let you enter your SSH password |
| –u [TARGET_USER] | it let you connect to the server as a user of this server, it’s the same user you connect when you SSH to the server |
| installAeroWebbDebian.yml | it is your playbook |
| inventory | it is your inventory file |
1.3 Troubleshooting and Questions¶
Why dies Ansible ask for two passwords when launching a Playbook?
When you launch a playbook Ansible will ask for two passwords: the first one is your SSH password, the second one is the root password. By default, the root password is the same as the SSH password, but it can be different if the targeted server is configured differently.
Why having an url in the playbook variables while we have already server IP address in Inventory?
In the Inventory, the targeted servers are connected by SSH, so we need IP address to do so, but you can configure Ansible to give Aero-Webb an URL like <http://aerowebb.lan> instead of its IP address.
I want to know what Ansible does when Installing Aero-Webb
You can add -v argument (for different levels of verbose, you can go up to vvvvv) in your terminal when executing your playbook, it will display logs about Aero-Webb deployment.
I can’t access Aero-Webb after deploying it with the Playbook
Check that your firewall (or iptables rules) is correctly configured on your server, and that your port 80 (default port for http) is open.
Why does the playbook create a tomcat.service file?
For security reasons, it is not recommended to start Tomcat with Root user but with a specific user. The playbook will create a Tomcat user who can start and stop Tomcat, managed by the Tomcat.service file. To use this file, please refer to your Linux distribution system documentation.
Why does the playbook create a Postgresql user named Aerowebb?
For security reasons, it is not recommended to connect to Aero-Webb database from the application with PostgreSQL user, but with a specific user. The playbook will create an Aero-Webb user in PostgreSQL who can access to Aero-Webb database.
Can I use these playbooks directly on Windows?
Due to technical limitations, Ansible is only compatible with Linux, but it can be launched on the Windows Subsystem for Linux (called WSL).
Using playbook step by step
For executing your playbook step by step, you can add --step argument in your command.
The playbook crashes with a sudoers error
In order to make the playbook work, you need to add the user you connect with SSH in the sudoers file; it will let Ansible execute installation commands and configure Apache and Tomcat.
1.4 5- Annexes¶
1.4.1 5.1 Ansible.cfg content¶
[ssh_connection]
pipelining=True
allow_world_readable_tmpfiles=true
[defaults]
log_path= ../logs/ansible.log
1.4.2 5.2- Example of inventory file¶
Created: 2024-02-13