Ansible Collection for Nextcloud Administration

This repository contains the nextcloud.admin Ansible Collection, which was previously known as the role aalaesar.install_nextcloud.

The collection provides various Ansible tools to help you manage Nextcloud and set up new instances.

Ansible Version Compatibility

This collection works with Ansible version 2.14.0 and up. Some plugins or modules may only work with specific versions of Ansible.

Python Support

The collection has been tested with Python version 3.11 and higher.

Supported Nextcloud Versions

This collection is compatible with Nextcloud versions: 25, 26, and 27 (latest).

Included Content

Modules

• nextcloud.admin.run_occ: Runs the OCC command line tool with specified arguments.

Roles

• nextcloud.admin.backup (beta): Creates a backup of a Nextcloud server (previously known as aalaesar.backup_nextcloud).
• nextcloud.admin.install_nextcloud: Installs and configures a Nextcloud instance on a Debian/Ubuntu server (previously known as aalaesar.install_nextcloud).

Installation and Usage

Dependencies

netaddr Python Library

This collection requires the netaddr library for network address manipulation. Install it using:

pip3 install netaddr

Required Standalone Roles

Some roles depend on additional standalone roles from other namespaces, which need to be installed manually after installing the collection. After installing the collection, run:

ansible-galaxy role install -r <this_collection_folder>/requirements.yml

Alternatively, add the content of this file to your own requirements.yml before installing the collection.

Installing the Collection from Ansible Galaxy

You need to install the collection with the Ansible Galaxy CLI before using it:

ansible-galaxy collection install nextcloud.admin

You can also include it in a requirements.yml file and install it with:

---
collections:
  - name: nextcloud.admin
    version: 2.0.0

Using Modules from the Collection in Your Playbooks

It is best to use the Fully Qualified Collection Namespace (FQCN) in your playbooks, like nextcloud.admin.run_occ:

---
- hosts: nextcloud_host
  gather_facts: false
  become: true
  tasks:
    - name: list installed apps
      nextcloud.admin.run_occ:
        nextcloud_path: /var/www/nextcloud
        command: app:list

If updating playbooks from version <2.0.0, minimize changes by defining collections in your play and using the role name install_nextcloud, like this:

---
- hosts: localhost
  gather_facts: false
  connection: local

  collections:
    - nextcloud.admin

  tasks:
    - name: deploy nextcloud and dependencies
      include_role:
        name: install_nextcloud

For documentation on how to use:

• Modules: use the ansible-doc command after installing the collection.
• Roles: check the README files for each role.

Testing and Development

To develop or improve this collection, clone it into one of the configured COLLECTIONS_PATHS and work there.

Testing with molecule

The tests directory contains playbooks for testing different scenarios. Integration tests are also in the molecule directory.

Publishing New Versions

New releases are automatically built and published to Ansible Galaxy when a new tag is created.

License

BSD

See LICENCE for the full text.