feat: document all roles and modules properly

.forgejo/workflows/ansible-galaxy.yml

@@ -0,0 +1,23 @@
+---
+
+name: Ansible Galaxy
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  deploy:
+    runs-on: docker
+    steps:
+
+      - uses: actions/checkout@v4
+      - name: Set version in galaxy.yml
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          sed -re "s/^version:.*$/version: ${VERSION}/" -i galaxy.yml
+      - name: Upload collection to Ansible Galaxy
+        uses: github.com/ansible/ansible-publish-action@v1.0.0
+        with:
+          api_key: ${{ secrets.GALAXY_API_KEY }}

.forgejo/workflows/ansible-lint.yml

@@ -0,0 +1,13 @@
+---
+
+name: Ansible Lint
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: docker
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run ansible-lint
+        uses: github.com/ansible/ansible-lint@main

galaxy.yml

@@ -8,7 +8,7 @@ namespace: s3lph
 name: nextcloud
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.0.2
+version: 0.0.3
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md
@@ -21,7 +21,7 @@ authors:
 
 ### OPTIONAL but strongly recommended
 # A short summary description of the collection
-description: Install and configure Nextcloud and PHP-FPM
+description: Install and configure Nextcloud and PHP-FPM.
 
 # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
 # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'

meta/runtime.yml

@@ -1,7 +1,7 @@
 ---
 # Collections must specify a minimum required ansible version to upload
 # to galaxy
-# requires_ansible: '>=2.9.10'
+requires_ansible: '>=2.9.10'
 
 # Content that Ansible needs to load from another location or that has
 # been deprecated/removed

plugins/modules/app.py

@@ -8,13 +8,11 @@ DOCUMENTATION = r'''
 ---
 module: config
 
-short_description: Set Nextcloud configuration options.
+short_description: Enable or disable Nextcloud apps.
 
-# If this is part of a collection, you need to use semantic versioning,
-# i.e. the version is of the form "2.5.0" and not "2.4".
 version_added: "0.0.1"
 
-description: Set Nextcloud configuration options via occ config.
+description: Enable or disable Nextcloud apps via C(occ app:).
 
 options:
     name:

plugins/modules/config.py

@@ -14,7 +14,7 @@ short_description: Set Nextcloud configuration options.
 # i.e. the version is of the form "2.5.0" and not "2.4".
 version_added: "0.0.1"
 
-description: Set Nextcloud configuration options via occ config.
+description: Set Nextcloud configuration options via C(occ config).
 
 options:
     system:
@@ -64,9 +64,9 @@ EXAMPLES = r'''
         host: localhost
         port: 6379
         dbindex: 0
-      memcache.local: "\OC\Memcache\Redis"
+      memcache.local: "\\OC\\Memcache\\Redis"
-      memcache.remote: "\OC\Memcache\Redis"
+      memcache.remote: "\\OC\\Memcache\\Redis"
-      memcache.locking: "\OC\Memcache\Redis"
+      memcache.locking: "\\OC\\Memcache\\Redis"
 '''
 
 

plugins/modules/install.py

@@ -8,13 +8,13 @@ DOCUMENTATION = r'''
 ---
 module: install
 
-short_description: Run occ maintenance:install
+short_description: Run C(occ maintenance:install)
 
 # If this is part of a collection, you need to use semantic versioning,
 # i.e. the version is of the form "2.5.0" and not "2.4".
 version_added: "0.0.1"
 
-description: Bootstrap Nextcloud with an invocation of occ maintenance:install.
+description: Bootstrap Nextcloud with an invocation of C(occ maintenance:install).
 
 options:
     database:
@@ -87,6 +87,22 @@ author:
 
 
 EXAMPLES = r'''
+- name: Perform Nextcloud first-time setup
+  become: true
+  become_user: www-data
+  s3lph.nextcloud.install:
+    webroot: /var/lib/nextcloud/webroot
+    data_dir: /var/lib/nextcloud/data
+    database: "mysql"
+    database_host: "localhost"
+    database_port: 3306
+    database_user: nextcloud
+    database_pass: changeme
+    database_name: nextcloud
+    admin_user: admin
+    admin_pass: changeme
+    admin_email: admin@example.org
+
 '''
 
 
@@ -98,7 +114,7 @@ status:
     sample:
         installed: true
         version: "25.0.3.2"
-        versionstring: "25.0.3
+        versionstring: "25.0.3"
         edition: ""
         maintenance: false
         needsDbUpgrade: false

plugins/modules/nextcloud_facts.py

@@ -10,11 +10,9 @@ module: nextcloud_facts
 
 short_description: Gather ansible_facts from Nextcloud.
 
-# If this is part of a collection, you need to use semantic versioning,
-# i.e. the version is of the form "2.5.0" and not "2.4".
 version_added: "0.0.1"
 
-description: Gather ansible_facts from Nextcloud via occ status and occ config:list.
+description: "Gather ansible_facts from Nextcloud via C(occ status) and C(occ config:list)."
 
 options:
     webroot:
@@ -50,7 +48,7 @@ ansible_facts.nextcloud_status:
     sample:
         installed: true
         version: "25.0.3.2"
-        versionstring: "25.0.3
+        versionstring: "25.0.3"
         edition: ""
         maintenance: false
         needsDbUpgrade: false

roles/keydb/defaults/main.yml

@@ -1,3 +1,3 @@
 ---
 
-php_version: "8.1"
+php_version: "8.2"

roles/keydb/meta/argument_specs.yml

@@ -0,0 +1,21 @@
+---
+
+argument_specs:
+
+  main:
+    version_added: "0.0.1"
+    short_description: Install and configure the Redis fork I(KeyDB).
+    description:
+      - Install and configure the Redis fork I(KeyDB) using their upstream repository.
+      - "Execution of this role can be limited using the following tags:"
+      - "C(role::keydb:install): Install keydb packages."
+      - "C(role::keydb:config): Render the keydb configuration file."
+      - "C(role::keydb): Apply all of the above."
+    author: s3lph
+    options:
+      php_version:
+        description:
+          - The installed PHP version.
+          - Required to restart C(php-fpm) after adding C(www-data) to the C(keydb) group.
+        type: str
+        default: "8.2"

roles/nextcloud/meta/argument_specs.yml

@@ -0,0 +1,121 @@
+---
+
+argument_specs:
+
+  main:
+    version_added: "0.0.1"
+    short_description: Install and configure Nextcloud.
+    description:
+      - Install and configure Nextcloud using the Debian packages from U(https://repo.s3lph.me).
+      - "Execution of this role can be limited using the following tags:"
+      - "C(role::nextcloud:install): Install packages and run C(occ maintenance:install) if not done."
+      - "C(role::nextcloud:config): Apply Nextcloud and app configuration options."
+      - "C(role::nextcloud): Apply all of the above."
+    author: s3lph
+    options:
+      nextcloud_major_version:
+        description: The version of Nextcloud to deploy.
+        type: str
+        default: "28"
+      nextcloud_trusted_domains:
+        description: The list of domains under which Nextcloud should be reachable.
+        type: list
+        elements: str
+        default:
+          - "cloud.example.org"
+      nextcloud_cli_baseurl:
+        description: The domain used when the C(occ) CLI tool is used to interact with  Nextcloud.
+        type: str
+        default: "https://cloud.example.org"
+
+      nextcloud_redis_host:
+        description: Hostname of the Redis server, or path of the UNIX socket, if O(nextcloud_redis_port) is 0.
+        type: str
+        default: /run/keydb/keydb.sock
+      nextcloud_redis_port:
+        description: Port of the Redis server, or 0 if a UNIX socket is used.
+        type: int
+        default: 0
+      nextcloud_redis_dbindex: 
+        description: Redis database index.
+        type: int
+        default: 0
+      nextcloud_redis_timeout:
+        description: Redis connection timeout.
+        type: float
+        default: 0.0
+
+      nextcloud_db_engine:
+        description: Database engine to use for Nextcloud.
+        type: str
+        default: mysql
+      nextcloud_db_host:
+        description: Hostname of the database server, or path of the UNIX socket, if O(nextcloud_db_port) is 0.
+        type: str
+        default: localhost
+      nextcloud_db_port:
+        description: Port of the database server, or 0 if a UNIX socket is used.
+        type: int
+        default: 3306
+      nextcloud_db_user:
+        description: Username to authenticate Nextcloud against the database server.
+        type: str
+        default: nextcloud
+      nextcloud_db_pass:
+        description: Password to authenticate Nextcloud against the database server.
+        type: str
+        required: true
+      nextcloud_db_name:
+        description: Name of the database that Nextcloud should use.
+        type: str
+        default: nextcloud
+
+      nextcloud_admin_user:
+        description: Username for the initial Nextcloud administrator account created on installation.
+        type: str
+        required: true
+      nextcloud_admin_pass:
+        description: Password for the initial Nextcloud administrator account created on installation.
+        type: str
+        required: true
+      nextcloud_admin_email:
+        description: E-Mail address for the initial Nextcloud administrator account created on installation.
+        type: str
+        required: true
+
+      nextcloud_enabled_apps:
+        description:
+          - List of nextcloud apps to be enabled.
+          - Apps that are not bundled with the Nextcloud installation are installed via O(nextcloud_app_packages).
+        type: list
+        elements: str
+        default: []
+      nextcloud_disabled_apps:
+        description:
+          - List of nextcloud apps to be disabled.
+        type: list
+        elements: str
+        default: []
+      nextcloud_app_packages:
+        description:
+          - The list of Nextcloud apps to install via Debian packages.
+          - By default, this is automatically compiled from the variable O(nextcloud_enabled_apps).
+        type: list
+        elements: str
+        default: []
+
+      nextcloud_system_configuration:
+        description:
+          - Nextcloud system config options and their values to apply.
+          - Options are set through C(occ config:set).
+          - Options must be provided as a dict of options as keys and their values as values.
+        type: dict
+        default: {}
+      nextcloud_apps_configuration:
+        description:
+          - Configuration options of individual apps and their values to apply.
+          - Options are set through C(occ config:app:set).
+          - Options must be provided as a nested dictionary.
+          - The outer dictionary maps app names to an inner dictionary of options and values.
+        type: dict
+        default: {}

roles/nextcloud/tasks/install.yml

@@ -1,14 +1,8 @@
 ---
 
-- name: Add repo.s3lph.me key
-  ansible.builtin.apt_key:
-    url: https://repo.s3lph.me/debian/repo.s3lph.me.gpg
-    keyring: /etc/apt/trusted.gpg.d/repo.s3lph.me.gpg
-
 - name: Add repo.s3lph.me
-  ansible.builtin.apt_repository:
+  ansible.builtin.apt:
-    filename: repo.s3lph.me.list
+    deb: https://git.kabelsalat.ch/s3lph/-/packages/debian/repo.s3lph.me-apt-source/0.2-2/files/3003
-    repo: deb https://repo.s3lph.me/debian stable main
 
 - name: Install apache2
   ansible.builtin.apt:
@@ -16,6 +10,7 @@
 
 - name: Install Nextcloud package
   ansible.builtin.apt:
+    update_cache: true
     name: "nextcloud-{{ nextcloud_major_version }}"
 
 - name: Gather Nextcloud facts

roles/php/defaults/main.yml

@@ -1,7 +1,7 @@
 ---
 
 php_version: "8.2"
-php_use_sury_repo: no
+php_use_sury_repo: false
 
 php_ini:
   PHP:

roles/php/meta/argument_specs.yml

@@ -0,0 +1,45 @@
+---
+
+argument_specs:
+
+  main:
+    version_added: "0.0.1"
+    short_description: Install and configure PHP FPM.
+    description:
+      - Install and configure PHP FPM.
+      - Installation is done either from distribution packages or from U(deb.sury.org).
+      - "Execution of this role can be limited using the following tags:"
+      - "C(role::php:install): Install all php packages required by Nextcloud."
+      - "C(role::php:config): Configure the PHP FPM and CLI components as recommended by Nextcloud."
+      - "C(role::php): Apply all of the above."
+    author: s3lph
+    options:
+      php_version:
+        description:
+          - The installed PHP version.
+          - Required to restart C(php-fpm) after adding C(www-data) to the C(keydb) group.
+        type: str
+        default: "8.2"
+      php_use_sury_repo:
+        description:
+          - If true, install PHP packages from U(deb.sury.org).
+          - If false, install PHP packages from the regular distribution packages.
+        type: bool
+        default: false
+      php_ini:
+        description:
+          - Nested dict of PHP configuration options.
+          - Outer dict defines the INI section, inner dict the options and their values.
+          - All options are applied to the FPM and CLI components of PHP.
+        type: dict
+        default:
+          PHP:
+            memory_limit: "512M"
+            upload_max_filesize: "2G"
+          opcache:
+            opcache.enable: "1"
+            opcache.memory_consumption: "256"
+            opcache.interned_strings_buffer: "32"
+            opcache.max_accelerated_files: "10000"
+            opcache.revalidate_freq: "60"
+            opcache.save_comments: "1"