= Setup QGIS and Lizmap Server Guide
:subject: How to use this ansible playbook to setup a lizmap web server
:description: Setup QGIS and Lizmap Server Guide
:keywords: gis, qgis, lizmap, linux, server, linux server, map, map editing, map management, ansible
:lang: en
:icons: font
:source-highlighter: rouge
:rouge-style: monokai
:pdf-theme: default-sans-with-font-fallbacks
:author_1: Gilex
:email_1: gilex-dev@proton.me
authorinitials_1: gilex
:toc:

== Run the playbook

Follow these steps to run the playbook successful.

[NOTE]
.User- and Hostname
====
We will use `test-host` as an example host and `manager` as the user, but it is recommended to use a custom username instead.

Use the `getent group sudo` command to check if the user you want to use has administrative rights.
====

=== Requirements

* Git
+
[,bash]
----
git clone https://somepi.ddns.net/gitea/gilex-dev/GisServer.git
cd GisServer
----

* Python venv
+
[,bash]
----
python3 -m venv ./.venv --system-site-packages
source ./.venv/bin/activate
pip3 install -r requirements.txt
ansible-galaxy install -r requirements.yaml
----

=== Adding your host

. Choose the inventory name used by ansible (this does not have to be the actual hostname) `export NEW_ANSIBLE_INV_NAME="testing-server-1"`

. Set hostname used by ansible `export NEW_ANSIBLE_HOST="test-host"`

. Set username used by ansible `export NEW_ANSIBLE_USER="manager"`
. 
+
[,bash]
----
ssh-keygen -a 100 -t ed25519 -C "a comment" -f ~/.ssh/id_$NEW_ANSIBLE_USER@NEW_ANSIBLE_HOST
ssh-keygen -a 100 -t ed25519 -C "another comment" -f ~/.ssh/id_publisher@$NEW_ANSIBLE_HOST
ssh-copy-id -i ~/.ssh/id_$NEW_ANSIBLE_USER@NEW_ANSIBLE_HOST $NEW_ANSIBLE_USER@$NEW_ANSIBLE_HOST
ssh-add ~/.ssh/id_$NEW_ANSIBLE_USER@NEW_ANSIBLE_HOST # optional, to remember key-phrase
----

. Add the host to the inventory `nano inventory.yaml` (keep other entries)
+
[,yaml]
----
testing: # or production or any other sensible group name
    hosts:
        # $NEW_ANSIBLE_INV_NAME: # or same as $NEW_ANSIBLE_HOST
            ansible_host: "{{ inventory_hostname }}" # or any address where the host is reachable
            ansible_user: # NEW_ANSIBLE_USER
            ansible_ssh_private_key_file: # ~/.ssh/id_$NEW_ANSIBLE_USER@$NEW_ANSIBLE_HOST
----

. Create a directory for the host `mkdir host_vars/$NEW_ANSIBLE_HOST`

. Copy the basic config file 
+
[,bash]
----
cp host_vars/variables.yaml.template host_vars/$NEW_ANSIBLE_HOST/variables.yaml
----

. Create the vault to store passwords needed by ansible
+
[,bash]
----
ansible-vault encrypt host_vars/secrets.yaml.template --output host_vars/$NEW_ANSIBLE_HOST/secrets.yaml`
----

. Edit the vault 
+
[,bash]
----
ansible-vault edit host_vars/$NEW_ANSIBLE_HOST/secrets.yaml
# Generate a new password for every entry (preferably A-z0-9 to avoid escape mishaps)
----

. Add the host config to your `~/.ssh/config` file to allow a simple ssh connection
+
[,config]
----
Host # e.g. $NEW_ANSIBLE_HOST
   HostName # $NEW_ANSIBLE_HOST
   User # $NEW_ANSIBLE_USER
   IdentityFile # ~/.ssh/id_$NEW_ANSIBLE_USER@NEW_ANSIBLE_HOST
   IdentitiesOnly yes
   VisualHostKey yes
----

. (optional) Clear env variables `unset NEW_ANSIBLE_HOST`, `unset NEW_ANSIBLE_USER` and `unset NEW_ANSIBLE_INV_NAME`

. Repeat for any other hosts you want to be managed by this playbook

=== Run ansible (finally)

If you don't want to make any changes in `host_vars/$NEW_ANSIBLE_HOST/variables.yaml` you can now run the playbook with the following command: 
[,bash]
----
ansible-playbook playbooks/main.yaml --ask-vault-pass
# or store the vault password in a file (e.g. `vault_password.txt`). !!!Only do this while testing!!!
# ansible-playbook playbooks/main.yaml --vault-password-file vault_password.txt
----

See the [ansible documentation](https://docs.ansible.com/ansible/latest/inventory_guide/intro_patterns.html) for specifying which hosts to target.

Don't panic if the following tasks take long to complete the first time you run the playbook on a host:

* `Ensure valid apt cache and required tools are present`
* `Ensure qgis-server is present`