Improving the install instructions

Created by: HizkiFW

I think the following passages are a bit ambiguous/hard to understand, and could be improved.

for "production server" we mean a server (not a laptop or a desktop computer!) with public ipv4 / ipv6 which is used to host openwisp2

for "local machine" we mean the host from which you launch ansible, eg: your own laptop

Ansible is a configuration management tool that works by entering production servers via SSH, so you need to install it and configure it on the machine where you launch the deployment and this machine must be able to SSH into the production server.

This section does not explain that ansible is going to install openwisp2 on the production server. It also needs to make it clear that the local machine is going to be installing openwisp2 on the production server by controlling it via ssh.

sudo ansible-galaxy install openwisp.openwisp2

Using sudo to install the openwisp2 role messed with some of the permissions, preventing ansible from reading the role. It could be fixed by chowning the role directory, but could easily be prevnted by not using sudo during this step.

Create a new file hosts on your local machine with the following contents:

Could be reworded to mention the working directory that was made in the previous step.

Create a new playbook file playbook.yml on your local machine with the following contents:

Also add instructions to replace the hosts part in the yml file to the production server's hostname

Substitute openwisp2.mydomain.com with your hostname - DO NOT REPLACE openwisp2.mydomain.com WITH AN IP ADDRESS, otherwise email sending through postfix will break, causing 500 internal server errors on some operations.

This is the part that confused me when I first installed it. It says to replace the hostname with your hostname, which is very ambiguous, since your could refer to either the local machine or the production server. Since the user is currently working on the local machine, it is assumed that the your here is the local machine, when in fact it should be the production server.

The line become: "{{ become | default('yes') }}" means ansible will use the sudo program to run each command. You may remove this line if you don't need it (eg: if you are using the root user).

This line could be improved by stating that the root user here is for the production server, not for the local machine.

Run the playbook from your local machine with:
ansible-playbook -i hosts playbook.yml -u <user> -k --become -K
Substitute <user> with your user.

'with your user' is ambiguous; it could mean either the local machine's username or the production server.

Tip: if you have an error like Authentication or permission failure then try to use root user ansible-playbook -i hosts playbook.yml -u root -k

Also add another tip, if there is an error about adding the host's fingerprint to the known_hosts file, it could be easily done by manually connecting to the host via SSH before doing the install process.

When the playbook is done running, if you got no errors you can login at:
https://openwisp2.mydomain.com/admin
username: admin
password: admin
Substitute openwisp2.mydomain.com with your hostname.

Again, 'your' here is ambiguous. Should be replaced with 'production server'.

I ~~will make~~ have made a PR fixing these issues.