From aeb2f592c627125e5febebdc890fe61d86b23a8a Mon Sep 17 00:00:00 2001 From: s3lph Date: Sun, 14 Apr 2024 19:12:40 +0200 Subject: [PATCH] feat: document all roles and modules properly --- .forgejo/workflows/ansible-galaxy.yml | 23 +++++ .forgejo/workflows/ansible-lint.yml | 13 +++ galaxy.yml | 4 +- meta/runtime.yml | 2 +- plugins/modules/app.py | 6 +- plugins/modules/config.py | 8 +- plugins/modules/install.py | 22 ++++- plugins/modules/nextcloud_facts.py | 6 +- roles/keydb/defaults/main.yml | 2 +- roles/keydb/meta/argument_specs.yml | 21 ++++ roles/nextcloud/meta/argument_specs.yml | 121 ++++++++++++++++++++++++ roles/nextcloud/tasks/install.yml | 11 +-- roles/php/defaults/main.yml | 2 +- roles/php/meta/argument_specs.yml | 45 +++++++++ 14 files changed, 258 insertions(+), 28 deletions(-) create mode 100644 .forgejo/workflows/ansible-galaxy.yml create mode 100644 .forgejo/workflows/ansible-lint.yml create mode 100644 roles/keydb/meta/argument_specs.yml create mode 100644 roles/nextcloud/meta/argument_specs.yml create mode 100644 roles/php/meta/argument_specs.yml diff --git a/.forgejo/workflows/ansible-galaxy.yml b/.forgejo/workflows/ansible-galaxy.yml new file mode 100644 index 0000000..76069c5 --- /dev/null +++ b/.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 }} diff --git a/.forgejo/workflows/ansible-lint.yml b/.forgejo/workflows/ansible-lint.yml new file mode 100644 index 0000000..6236fe1 --- /dev/null +++ b/.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 diff --git a/galaxy.yml b/galaxy.yml index 8736dd4..8bad77b 100644 --- a/galaxy.yml +++ b/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' diff --git a/meta/runtime.yml b/meta/runtime.yml index 20f709e..2fe301c 100644 --- a/meta/runtime.yml +++ b/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 diff --git a/plugins/modules/app.py b/plugins/modules/app.py index 1a2b08c..7dab1d3 100644 --- a/plugins/modules/app.py +++ b/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: diff --git a/plugins/modules/config.py b/plugins/modules/config.py index 3e96d85..239b325 100644 --- a/plugins/modules/config.py +++ b/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.remote: "\OC\Memcache\Redis" - memcache.locking: "\OC\Memcache\Redis" + memcache.local: "\\OC\\Memcache\\Redis" + memcache.remote: "\\OC\\Memcache\\Redis" + memcache.locking: "\\OC\\Memcache\\Redis" ''' diff --git a/plugins/modules/install.py b/plugins/modules/install.py index 857be0c..7246d38 100644 --- a/plugins/modules/install.py +++ b/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 diff --git a/plugins/modules/nextcloud_facts.py b/plugins/modules/nextcloud_facts.py index 75b7ea7..32ebbf3 100644 --- a/plugins/modules/nextcloud_facts.py +++ b/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 diff --git a/roles/keydb/defaults/main.yml b/roles/keydb/defaults/main.yml index 133f228..a33894c 100644 --- a/roles/keydb/defaults/main.yml +++ b/roles/keydb/defaults/main.yml @@ -1,3 +1,3 @@ --- -php_version: "8.1" +php_version: "8.2" diff --git a/roles/keydb/meta/argument_specs.yml b/roles/keydb/meta/argument_specs.yml new file mode 100644 index 0000000..a316a22 --- /dev/null +++ b/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" diff --git a/roles/nextcloud/meta/argument_specs.yml b/roles/nextcloud/meta/argument_specs.yml new file mode 100644 index 0000000..184d290 --- /dev/null +++ b/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: {} diff --git a/roles/nextcloud/tasks/install.yml b/roles/nextcloud/tasks/install.yml index 987c409..8e5d3a5 100644 --- a/roles/nextcloud/tasks/install.yml +++ b/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: - filename: repo.s3lph.me.list - repo: deb https://repo.s3lph.me/debian stable main + ansible.builtin.apt: + deb: https://git.kabelsalat.ch/s3lph/-/packages/debian/repo.s3lph.me-apt-source/0.2-2/files/3003 - 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 diff --git a/roles/php/defaults/main.yml b/roles/php/defaults/main.yml index 6a88178..1521dc9 100644 --- a/roles/php/defaults/main.yml +++ b/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: diff --git a/roles/php/meta/argument_specs.yml b/roles/php/meta/argument_specs.yml new file mode 100644 index 0000000..0448ac5 --- /dev/null +++ b/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"