Changeset - 2ecdd0639863
Parent rev.
Child rev.
[Not reviewed]
0 1 0
Branko Majic (branko) - 10 days ago 2024-09-09 13:24:10
branko@majic.rs
MAR-218: Update the usage tasks and instructions for Ansible 10.3:

- Update the module names to include the namespace.
- Drop references to Python 3, and bump up the installed package
versions.
1 file changed with 27 insertions and 28 deletions:
docs/usage.rst
27
28
0 comments (0 inline, 0 general)
docs/usage.rst
➞
Show inline comments
 
@@ -124,27 +124,27 @@ packages, and to prepare the environment a bit on the Ansible server:
 
     ln -s /usr/share/bash-completion/completions/virtualenvwrapper /etc/bash_completion.d/virtualenvwrapper
 

			




	
	
	
		
 
3. Set-up the virtual environment (using the ``ansible`` account):

			




	
	
	
		
 

			




	
	
	
		
 
   .. warning::

			




	
	
	
		
 
      If you are already logged-in as user ``ansible`` in the server, you will

			




	
	
	
		
 
      need to log-out and log-in again in order to be able to use

			




	
	
	
		
 
      ``virtualenvwrapper`` commands!

			




	
	
	
		
 

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
     mkdir ~/mysite/

			




	
	
	
		
 
     mkvirtualenv -p /usr/bin/python3 -a ~/mysite/ mysite

			




	
	
	
		
 
     mkvirtualenv -a ~/mysite/ mysite

			




	
	
	
		
 
     pip install -U pip setuptools

			




	
	
	
		
 
     pip install 'ansible~=2.9.0' netaddr

			




	
	
	
		
 
     pip install 'ansible~=10.3.0' netaddr

			




	
	
	
		
 

			




	
	
	
		
 
.. warning::

			




	
	
	
		
 
   The ``netaddr`` package is needed for ``ipv4/ipv6`` lookup plugins

			




	
	
	
		
 
   which is used internally by some of the roles.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Cloning the *Majic Ansible Roles*

			




	
	
	
		
 
---------------------------------

			




	
	
	
		
 

			




	
	
	
		
 
With most of the software pieces in place, the only missing thing is the Majic

			




	
	
	
		
 
Ansible Roles:

			




	
	
	
		
 

			




	
	
		
 
@@ -179,25 +179,24 @@ First of all, let's set-up some basic directory structure and configuration:

			




	
	
	
		
 
      <https://docs.ansible.com/ansible/latest/become.html#becoming-an-unprivileged-user>`_

			




	
	
	
		
 
      and other alternatives to this.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/ansible.cfg`

			




	
	
	
		
 

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
     [defaults]

			




	
	
	
		
 

			




	
	
	
		
 
     roles_path=/home/ansible/majic-ansible-roles/roles:/home/ansible/mysite/roles

			




	
	
	
		
 
     force_handlers = True

			




	
	
	
		
 
     inventory = /home/ansible/mysite/hosts

			




	
	
	
		
 
     interpreter_python = /usr/bin/python3

			




	
	
	
		
 

			




	
	
	
		
 
     [ssh_connection]

			




	
	
	
		
 
     pipelining = True

			




	
	
	
		
 

			




	
	
	
		
 
2. Create directory where retry files will be stored at (so they woudln't

			




	
	
	
		
 
   pollute your home directory)::

			




	
	
	
		
 

			




	
	
	
		
 
     mkdir ~/mysite/retry

			




	
	
	
		
 

			




	
	
	
		
 
3. Create the inventory file.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/hosts`

			




	
	
		
 
@@ -1542,141 +1541,141 @@ Before we start, here is a couple of useful pointers regarding the

			




	
	
	
		
 
4. Time to get our hands a bit more dirty... Up until now we didn't

			




	
	
	
		
 
   have to write custom tasks, but that ends now.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/roles/nextcloud/tasks/main.yml`

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
      ---

			




	
	
	
		
 

			




	
	
	
		
 
      # Deployment

			




	
	
	
		
 
      # ==========

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Download the application archive

			




	
	
	
		
 
        get_url:

			




	
	
	
		
 
        ansible.builtin.get_url:

			




	
	
	
		
 
          url: "https://download.nextcloud.com/server/releases/nextcloud-28.0.3.tar.bz2"

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/nextcloud-28.0.3.tar.gz"

			




	
	
	
		
 
          sha256sum: "9ed413c0de16f5b033ceeffcca99c0d61fc698dbeb8db851ac9adf9eef951906"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: admin-nextcloud_example_com

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Unpack the application archive

			




	
	
	
		
 
        unarchive:

			




	
	
	
		
 
        ansible.builtin.unarchive:

			




	
	
	
		
 
          src: "/var/www/nextcloud.example.com/nextcloud-28.0.3.tar.gz"

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/"

			




	
	
	
		
 
          copy: no

			




	
	
	
		
 
          creates: "/var/www/nextcloud.example.com/nextcloud"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: admin-nextcloud_example_com

			




	
	
	
		
 

			




	
	
	
		
 
      # Majic Ansible Roles currently only support utf8 encoding.

			




	
	
	
		
 
      - name: Disable opportunistic use of utf8mb4 on fresh installs

			




	
	
	
		
 
        lineinfile:

			




	
	
	
		
 
        ansible.builtin.lineinfile:

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/nextcloud/lib/private/Setup/MySQL.php"

			




	
	
	
		
 
          line: "{{ '\t\t\t' }}$this->config->setValue('mysql.utf8mb4', true);"

			




	
	
	
		
 
          state: absent

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Allow application user to install and update applications

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/nextcloud/apps"

			




	
	
	
		
 
          mode: g+w

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Allow CLI tool to be run by the user and group

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/nextcloud/occ"

			




	
	
	
		
 
          mode: u+x,g+x

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Create directory for storing data

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/data"

			




	
	
	
		
 
          state: directory

			




	
	
	
		
 
          mode: 02770

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Create directory for storing configuration files

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/nextcloud/config"

			




	
	
	
		
 
          state: directory

			




	
	
	
		
 
          mode: 02750

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Create an empty log file if it does not exist

			




	
	
	
		
 
        copy:

			




	
	
	
		
 
        ansible.builtin.copy:

			




	
	
	
		
 
          content: ""

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/data/nextcloud.log"

			




	
	
	
		
 
          force: no

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Set-up log file permissions

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/data/nextcloud.log"

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 
          mode: 0660

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Symlink the default path used by the web server for finding application files

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          src: "/var/www/nextcloud.example.com/nextcloud"

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/htdocs"

			




	
	
	
		
 
          state: link

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 
        notify:

			




	
	
	
		
 
          - Restart PHP-FPM

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
      # Installation

			




	
	
	
		
 
      # ============

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Get application installation status

			




	
	
	
		
 
        command: "/var/www/nextcloud.example.com/nextcloud/occ status"

			




	
	
	
		
 
        ansible.builtin.command: "/var/www/nextcloud.example.com/nextcloud/occ status"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: "admin-nextcloud_example_com"

			




	
	
	
		
 
        register: nextcloud_status

			




	
	
	
		
 
        changed_when: False

			




	
	
	
		
 
        failed_when: False

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Check if application is installed

			




	
	
	
		
 
        set_fact:

			




	
	
	
		
 
        ansible.builtin.set_fact:

			




	
	
	
		
 
          nextcloud_installed: "{{ 'Nextcloud is not installed' not in nextcloud_status.stderr }}"

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Deploy installation script

			




	
	
	
		
 
        copy:

			




	
	
	
		
 
        ansible.builtin.copy:

			




	
	
	
		
 
          src: "install_nextcloud.py"

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/install_nextcloud.py"

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 
          mode: 0700

			




	
	
	
		
 
        when: "not nextcloud_installed"

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Install application

			




	
	
	
		
 
        command: "/var/www/nextcloud.example.com/install_nextcloud.py"

			




	
	
	
		
 
        ansible.builtin.command: "/var/www/nextcloud.example.com/install_nextcloud.py"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: "admin-nextcloud_example_com"

			




	
	
	
		
 
        when: "not nextcloud_installed"

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Remove installation script

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/install_nextcloud.py"

			




	
	
	
		
 
          state: absent

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Fix data file permissions for application user/group

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          path: "/var/www/nextcloud.example.com/data"

			




	
	
	
		
 
          mode: g+w

			




	
	
	
		
 
          recurse: yes

			




	
	
	
		
 
          follow: no

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Deploy local configuration overrides

			




	
	
	
		
 
        copy:

			




	
	
	
		
 
        ansible.builtin.copy:

			




	
	
	
		
 
          src: "local.config.php"

			




	
	
	
		
 
          dest: "/var/www/nextcloud.example.com/nextcloud/config/local.config.php"

			




	
	
	
		
 
          owner: "admin-nextcloud_example_com"

			




	
	
	
		
 
          group: "web-nextcloud_example_com"

			




	
	
	
		
 
          mode: 0640

			




	
	
	
		
 

			




	
	
	
		
 
5. Set-up files that are deployed by the role.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/roles/nextcloud/files/local.config.php`

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
      <?php

			




	
	
		
 
@@ -1919,87 +1918,87 @@ on the safe side:

			




	
	
	
		
 
        certtool --sec-param normal --generate-privkey --outfile ~/mysite/tls/wiki.example.com_https.key

			




	
	
	
		
 
        certtool --generate-certificate --load-ca-privkey ~/mysite/tls/ca.key --load-ca-certificate ~/mysite/tls/ca.pem --template ~/mysite/tls/wiki.example.com_https.cfg --load-privkey ~/mysite/tls/wiki.example.com_https.key --outfile ~/mysite/tls/wiki.example.com_https.pem

			




	
	
	
		
 

			




	
	
	
		
 
4. At this point we have exhausted what we can do with the built-in roles. Time

			




	
	
	
		
 
   to add some custom tasks.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/roles/wiki/tasks/main.yml`

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
      ---

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Create Django project directory

			




	
	
	
		
 
        file:

			




	
	
	
		
 
        ansible.builtin.file:

			




	
	
	
		
 
          dest: "/var/www/wiki.example.com/code"

			




	
	
	
		
 
          state: directory

			




	
	
	
		
 
          owner: admin-wiki_example_com

			




	
	
	
		
 
          group: web-wiki_example_com

			




	
	
	
		
 
          mode: 02750

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Start Django project for the Wiki website

			




	
	
	
		
 
        command: "/var/www/wiki.example.com/virtualenv/bin/exec django-admin startproject wiki_example_com /var/www/wiki.example.com/code"

			




	
	
	
		
 
        ansible.builtin.command: "/var/www/wiki.example.com/virtualenv/bin/exec django-admin startproject wiki_example_com /var/www/wiki.example.com/code"

			




	
	
	
		
 
        args:

			




	
	
	
		
 
          chdir: "/var/www/wiki.example.com"

			




	
	
	
		
 
          creates: "/var/www/wiki.example.com/code/wiki_example_com"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: admin-wiki_example_com

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Deploy settings for wiki website

			




	
	
	
		
 
        copy:

			




	
	
	
		
 
        ansible.builtin.copy:

			




	
	
	
		
 
          src: "{{ item }}"

			




	
	
	
		
 
          dest: "/var/www/wiki.example.com/code/wiki_example_com/{{ item }}"

			




	
	
	
		
 
          mode: 0640

			




	
	
	
		
 
          owner: admin-wiki_example_com

			




	
	
	
		
 
          group: web-wiki_example_com

			




	
	
	
		
 
        with_items:

			




	
	
	
		
 
          - settings.py

			




	
	
	
		
 
          - urls.py

			




	
	
	
		
 
        notify:

			




	
	
	
		
 
          - Restart wiki

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Deploy project database and deploy static files

			




	
	
	
		
 
        django_manage:

			




	
	
	
		
 
        community.general.django_manage:

			




	
	
	
		
 
          command: "{{ item }}"

			




	
	
	
		
 
          app_path: "/var/www/wiki.example.com/code/"

			




	
	
	
		
 
          virtualenv: "/var/www/wiki.example.com/virtualenv/"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: admin-wiki_example_com

			




	
	
	
		
 
        with_items:

			




	
	
	
		
 
          - migrate

			




	
	
	
		
 
          - collectstatic

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Deploy the superuser creation script

			




	
	
	
		
 
        copy:

			




	
	
	
		
 
        ansible.builtin.copy:

			




	
	
	
		
 
          src: "create_superuser.py"

			




	
	
	
		
 
          dest: "/var/www/wiki.example.com/code/create_superuser.py"

			




	
	
	
		
 
          owner: admin-wiki_example_com

			




	
	
	
		
 
          group: web-wiki_example_com

			




	
	
	
		
 
          mode: 0750

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Create initial superuser

			




	
	
	
		
 
        command: "/var/www/wiki.example.com/virtualenv/bin/exec ./create_superuser.py"

			




	
	
	
		
 
        ansible.builtin.command: "/var/www/wiki.example.com/virtualenv/bin/exec ./create_superuser.py"

			




	
	
	
		
 
        args:

			




	
	
	
		
 
          chdir: "/var/www/wiki.example.com/code/"

			




	
	
	
		
 
        become: yes

			




	
	
	
		
 
        become_user: admin-wiki_example_com

			




	
	
	
		
 
        register: wiki_superuser

			




	
	
	
		
 
        changed_when: "wiki_superuser.stdout ==  'Created superuser.'"

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/roles/wiki/handlers/main.yml`

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
      ---

			




	
	
	
		
 

			




	
	
	
		
 
      - name: Restart wiki

			




	
	
	
		
 
        service:

			




	
	
	
		
 
        ansible.builtin.service:

			




	
	
	
		
 
          name: wiki.example.com

			




	
	
	
		
 
          state: restarted

			




	
	
	
		
 

			




	
	
	
		
 
5. There is a couple of files that we are deploying through the above

			




	
	
	
		
 
   tasks. Let's create them as well.

			




	
	
	
		
 

			




	
	
	
		
 
   :file:`~/mysite/roles/wiki/files/settings.py`

			




	
	
	
		
 
   ::

			




	
	
	
		
 

			




	
	
	
		
 
      """

			




	
	
	
		
 
      Django settings for wiki_example_com project.

			




	
	
	
		
 

			




	
	
		
 
@@ -2575,25 +2574,25 @@ No packages will be upgraded automatically - ensuring you can make sure upgrades

			




	
	
	
		
 
work correctly and do not cause major outage without anyone being present to

			




	
	
	
		
 
fix them.

			




	
	
	
		
 

			




	
	
	
		
 
Another useful package you may want to look into is ``needrestart`` - which runs

			




	
	
	
		
 
as a hook during the upgrade process to detect any processes that seem to be

			




	
	
	
		
 
running with outdated libraries, allowing you to restart them as well. This

			




	
	
	
		
 
package is *not* installed by the ``common`` role out-of-the-box, but you can

			




	
	
	
		
 
easily do so by updating the ``common_packages`` setting.

			




	
	
	
		
 

			




	
	
	
		
 
In addition to system packages, the ``common`` role makes it easy to check if

			




	
	
	
		
 
any of the pip requirements files are outdated as well. It should be noted,

			




	
	
	
		
 
though, that this check does *not* verify the Python virtual environments

			




	
	
	
		
 
themselves. Only Python 3 is supported at this time.

			




	
	
	
		
 
themselves.

			




	
	
	
		
 

			




	
	
	
		
 
This is primarily useful when you use `pip-tools

			




	
	
	
		
 
<https://github.com/jazzband/pip-tools>`_ for maintaining the

			




	
	
	
		
 
requirements files. In fact, I would encourage you to utilise

			




	
	
	
		
 
``pip-tools`` for both this purpose and for keeping the virtual

			




	
	
	
		
 
environment in sync and up-to-date.

			




	
	
	
		
 

			




	
	
	
		
 
Roles that want to take advantage of this would:

			




	
	
	
		
 

			




	
	
	
		
 
- Create a sub-directory under

			




	
	
	
		
 
  ``/etc/pip_check_requirements_upgrades/``.

			




	
	
	
		
 
- Deploy ``.in`` and ``.txt`` files within the sub-directory (see ``pip-tools``

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2024 by various authors & licensed under GPLv3.