Changed main documentation format to AsciiDocs and added links to roles

README.adoc

@@ -0,0 +1,16 @@
+= Ansible roles to manage my infrastructure
+
+This repository contains a collection of roles I wrote to automate my infrastructure's deployment. My homelab consists in few services mainly running in Docker containers through compose files in Debian VMs in a Proxmox host. This also comes at the time I'm migrating from Nginx to Caddy to simplify my configurations and also escape some limitations I was experimenting (since I was using NPM and not vanilla Nginx). Here are the roles I'm working on:
+
+* link:./roles/bootstrap_vm/README.adoc[VM bootstrap using template]
+* link:./roles/docker/README.adoc[Docker installation]
+* link:./roles/unattended-upgrades/README.adoc[Auto upgrades]
+* Caddy setup
+* link:./roles/wireguard/README.adoc[Wireguard setup]
+* Nextcloud setup
+* Gitea setup
+* Hedgedoc setup
+* Mealie setup
+* Scrutiny setup
+* Rustdesk setup
+* Cryptpad setup

README.rst

@@ -1,16 +0,0 @@
-Ansible roles to manage my infrastructure
-=========================================
-
-This repository contains simple roles I wrote to automate my infrastructure's deployment. My homelab consists in few services mainly running in Docker containers through compose files in Debian VMs in a Proxmox host. This also comes at the time I'm migrating from Nginx to Caddy to simplify my configurations and also escape some limitations I was experimenting (since I was using NPM and not vanilla Nginx). Here are the roles I'm working on:
-
-* VM installation through already existing template
-* Docker installation
-* Caddy setup
-* Wireguard setup
-* Nextcloud setup
-* Gitea setup
-* Hedgedoc setup
-* Mealie setup
-* Scrutiny setup
-* Rustdesk setup
-* Cryptpad setup

roles/unattended-upgrades/README.adoc

@@ -0,0 +1,90 @@
+= Unattended-upgrades setup
+
+Unattended-upgrades setup role. It also installs and configures Postfix as a SMTP relay in order to send emails when target system needs to be rebooted.
+
+== Requirements
+
+This role was written for Debian (tested on >= 11) and requires root privileges.
+
+== Role Variables
+
+Variables can be found in the link:./defaults/main.yml[default vars file]. As a bare minimum you should configure SMTP credentials.
+
+[source,yaml]
+----
+upgrades_sender: "{{ ansible_user }}@{{ ansible_hostname }}.lan"
+----
+
+Defines which email unattended-upgrades will use to send emails.
+
+[source,yaml]
+----
+postfix_hostname: "{{ ansible_hostname }}.lan"
+----
+
+Configures Postfix hostname.
+
+[source,yaml]
+----
+smtp_username:
+smtp_password:
+smtp_port: 587
+----
+
+SMTP credentials (required). Port defaults to 587 (STARTTLS).
+
+[source,yaml]
+----
+relay_servername: "{{ smtp_username | regex_search('(?<=@)(.+)\\.[\\w]+$') }}"
+----
+
+SMTP servername, defaults to `smtp_username` domain. If yours differs modify it here.
+
+[source,yaml]
+----
+custom_smtp_header: false
+from_header:
+from_email:
+----
+
+Customizes SMTP header. Make sure to configure `from_header` (added header) and `from_email` (email address of FROM) correctly if you enable SMTP headers variable.
+
+[source,yaml]
+----
+smtp_masquerade: false
+----
+
+SMTP masquerade allows to replace the FROM statement to the value of `smtp_username`.
+
+[source,yaml]
+----
+additional_lists: []
+----
+
+List of additional sources lists you want to add to unattended-upgrades.
+
+== Dependencies
+
+None.
+
+== Example Playbook
+
+[source,yaml]
+----  
+- name: Deploy automatic upgrades
+  hosts: all
+  become: true
+  vars:
+    smtp_username: user@domain.com
+    smtp_password: pa$$word      
+  roles:
+    - role: 'unattended-upgrades'
+----
+
+== License
+
+BSD-3
+
+== Author Information
+
+Role created by https://git.syyrell.com/syrell[syrell].

roles/unattended-upgrades/README.rst

@@ -1,89 +0,0 @@
-Unattended-upgrades setup
-=========================
-
-Unattended-upgrades setup role. It also installs and configures Postfix as a SMTP relay in order to send emails when target system needs to be rebooted.
-
-Requirements
-------------
-
-This role was written for Debian (11) and requires root privileges.
-
-Role Variables
---------------
-
-Variables can be found in the `default vars <defaults/main.yml>`_. As a bare minimum you should configure SMTP credentials.
-
-.. code-block:: yaml
-
-  upgrades_sender: "{{ ansible_user }}@{{ ansible_hostname }}.lan"
-
-Defines which email unattended-upgrades will use to send emails.
-
-.. code-block:: yaml
-
-  postfix_hostname: "{{ ansible_hostname }}.lan"
-
-Configures Postfix hostname.
-
-.. code-block:: yaml
-
-  smtp_username:
-  smtp_password:
-  smtp_port: 587
-
-SMTP credentials (required). Port defaults to 587 (STARTTLS).
-
-.. code-block::yaml
-
-  relay_servername: "{{ smtp_username | regex_search('(?<=@)(.+)\\.[\\w]+$') }}"
-
-SMTP servername, defaults to ``smtp_username`` domain. If yours differs modify it here.
-
-.. code-block:: yaml
-
-  custom_smtp_header: false
-  from_header:
-  from_email:
-
-Customizes SMTP header. Make sure to configure ``from_header`` (added header) and ``from_email`` (email address of FROM) correctly if you enable SMTP headers variable.
-
-.. code-block:: yaml
-
-  smtp_masquerade: false
-
-SMTP masquerade allows to replace the FROM statement to the value of ``smtp_username``.
-
-.. code-block:: yaml
-
-  additional_lists: []
-
-List of additional sources lists you want to add to unattended-upgrades.
-
-Dependencies
-------------
-
-None.
-
-Example Playbook
-----------------
-
-.. code-block:: yaml
-  
-  - name: Deploy automatic upgrades
-    hosts: all
-    become: true
-    vars:
-      smtp_username: user@domain.com
-      smtp_password: pa$$word      
-    roles:
-      - role: 'unattended-upgrades'
-
-License
--------
-
-BSD-3
-
-Author Information
-------------------
-
-Role created by `syrell <https://git.syyrell.com/syrell>`_.

roles/wireguard/README.adoc

@@ -0,0 +1,133 @@
+= Wireguard setup
+
+Wireguard setup role. This role extends https://github.com/lablabs/ansible-collection-wireguard/tree/main/roles/wireguard[this codebase] to my needs. It's a bit simpler and adds more idempotence, e.g. when replaying the role to add another client to the server.   
+
+== Requirements
+
+This role was written for Debian (tested on >=11) and requires root privileges. It also requires to have several collections installed on your ansible host you won't necessarily have depending on your Ansible installation:
+
+- ansible.posix
+- community.general (iptables_save module)
+- ansible.utils (network filters)
+- netaddr (python package)
+
+== Role Variables
+
+Variables can be found in the link:./defaults/main.yml[default vars file].
+
+[source,yaml]
+----
+wireguard_dir: /etc/wireguard
+wireguard_clients_dir: "{{ wireguard_dir }}/clients"
+wireguard_clients_download_dir: clients/
+wireguard_download_clients: false
+wireguard_serverkeys_download_dir: server/
+wireguard_download_serverkeys: false
+----
+
+Defines basic arborescence to store Wireguard files. `wireguard_download_clients` and `wireguard_download_serverkeys` can optionally set to true in order to download respectively clients and server's keys from the target host.
+
+[source,yaml]
+----
+wireguard_restore_serverkeys_dir: ""
+----
+
+Use this variable if you want to use pre-existing keys from a directory to bootstrap Wireguard. Must ends with '/'.
+
+[source,yaml]
+----
+wireguard_packages:
+- wireguard
+----
+
+List of packages to install.
+
+[source,yaml]
+----
+wireguard_port: 51810
+----
+
+Port which Wireguard will listen to.
+
+[source,yaml]
+----
+wireguard_hostname: "{{ inventory_hostname }}"
+----
+
+Hostname the client will use to connect to the server.
+
+[source,yaml]
+----
+wireguard_interface: wg0
+----
+
+Interface which will be mounted to the server.
+
+[source,yaml]
+----
+nat_out_interface: eth0
+----
+
+Interface where the traffic will be NATed to on the server.
+
+[source,yaml]
+----
+wireguard_address: 10.213.213.0/24
+----
+
+Subnet definition for the VPN network.
+
+[source,yaml]
+----
+wireguard_keepalive: 25
+----
+
+Uses this if you wanna specify a keepalive value. See https://github.com/pirate/wireguard-docs#persistentkeepalive[this] for more information on keepalive.
+
+[source,yaml]
+----
+wireguard_peers: []
+----
+
+Lits of peers (clients) you wanna create. You can define specific name, address, allowedIPs, DNS and keepalive for each peer. See playbook below for example.
+
+[source,yaml]
+----
+filter_forward: false
+other_interface:
+----
+
+Set `filter_forward` to true and specify an interface name for `other_interface` if you wanna drop packets from `wireguard_interface` to this interface.
+
+== Dependencies
+
+None.
+
+== Example Playbook
+
+[source,yaml]
+----
+- name: Deploy Wireguard
+  hosts: wireguard_hosts
+  become: true
+  vars:
+    wireguard_hostname: "mywireguard.server.com"
+    wireguard_address: 10.10.10.0/24
+    wireguard_peers:
+      - name: client_001
+        allowed_ip: "0.0.0.0/0, ::/0"
+        address: "10.10.10.2"
+      - name: client_002
+        allowed_ip: "0.0.0.0/0, ::/0"
+        address: "10.10.10.3"
+  roles:
+    - wireguard
+----
+
+== License
+
+BSD-3
+
+== Author Information
+
+Role created by https://git.syyrell.com/syrell[syrell].

roles/wireguard/README.rst

@@ -1,128 +0,0 @@
-Wireguard setup
-===============
-
-Wireguard setup role. This role extends `this codebase <https://github.com/lablabs/ansible-collection-wireguard/tree/main/roles/wireguard>`_ to my needs. It's a bit simpler and adds more idempotence, e.g. when replaying the role to add another client to the server.   
-
-Requirements
-------------
-
-This role was written for Debian (11) and requires root privileges. It also requires to have several collections installed on your ansible host you won't necessarily have depending on your Ansible installation:
-
-- ansible.posix
-- community.general (iptables_save module)
-- ansible.utils (network filters)
-- netaddr (python package)
-
-Role Variables
---------------
-
-Variables can be found in the `default vars <defaults/main.yml>`_
-
-.. code-block:: yaml
-
-  wireguard_dir: /etc/wireguard
-  wireguard_clients_dir: "{{ wireguard_dir }}/clients"
-  wireguard_clients_download_dir: clients/
-  wireguard_download_clients: false
-  wireguard_serverkeys_download_dir: server/
-  wireguard_download_serverkeys: false
-
-Defines basic arborescence to store Wireguard files. ``wireguard_download_clients`` and ``wireguard_download_serverkeys`` can optionally set to true in order to download respectively clients and server's keys from the target host.
-
-.. code-block:: yaml
-
-  wireguard_restore_serverkeys_dir: ""
-
-Use this variable if you want to use pre-existing keys from a directory to bootstrap Wireguard. Must ends with '/'.
-
-.. code-block:: yaml
-
-  wireguard_packages:
-  - wireguard
-
-List of packages to install.
-
-.. code-block:: yaml
-
-  wireguard_port: 51810
-
-Port which Wireguard will listen to.
-
-.. code-block:: yaml
-
-  wireguard_hostname: "{{ inventory_hostname }}"
-
-Hostname the client will use to connect to the server.
-
-.. code-block:: yaml
-
-  wireguard_interface: wg0
-
-Interface which will be mounted to the server.
-
-.. code-block:: yaml
-
-  nat_out_interface: eth0
-
-Interface where the traffic will be NATed to on the server.
-
-.. code-block:: yaml
-
-  wireguard_address: 10.213.213.0/24
-
-Subnet definition for the VPN network.
-
-.. code-block:: yaml
-
-  wireguard_keepalive: 25
-
-Uses this if you wanna specify a keepalive value. See `this <https://github.com/pirate/wireguard-docs#persistentkeepalive>`_ for more information on keepalive.
-
-.. code-block:: yaml
-
-  wireguard_peers: []
-
-Lits of peers (clients) you wanna create. You can define specific name, address, allowedIPs, DNS and keepalive for each peer. See playbook below for example.
-
-.. code-block:: yaml
-
-  filter_forward: false
-  other_interface:
-
-Set ``filter_forward`` to true and specify an interface name for ``other_interface`` if you wanna drop packets from ``wireguard_interface`` to this interface.
-
-Dependencies
-------------
-
-None.
-
-Example Playbook
-----------------
-
-.. code-block:: yaml
-
-  - name: Deploy Wireguard
-    hosts: wireguard_hosts
-    become: true
-    vars:
-      wireguard_hostname: "mywireguard.server.com"
-      wireguard_address: 10.10.10.0/24
-      wireguard_peers:
-        - name: client_001
-          allowed_ip: "0.0.0.0/0, ::/0"
-          address: "10.10.10.2"
-        - name: client_002
-          allowed_ip: "0.0.0.0/0, ::/0"
-          address: "10.10.10.3"
-    roles:
-      - wireguard
-
-License
--------
-
-BSD-3
-
-Author Information
-------------------
-
-Role created by `syrell <https://git.syyrell.com/syrell>`_