Documentation enhancements pr 1.x

README.md

@@ -1,11 +1,10 @@
 # ce-deploy
 
-[![Build Status](https://api.travis-ci.com/codeenigma/ce-deploy.svg?branch=1.x)](https://api.travis-ci.com/codeenigma/ce-deploy.svg?branch=1.x)
-
 A set of Ansible roles and wrapper scripts to deploy (web) applications.
+
 ## Overview
 The "stack" from this repo is to be installed on a "deploy" server/runner, to be used in conjonction with a CI/CD tool (Jenkins, Gitlab, Travis, ...).
-It allows the deploy steps for a given app to be easily customizable at will, and to be stored alongside the codebase of the project.
+It allows the deploy steps for a given app to be easily customisable and to be stored alongside the codebase of the project.
 When triggered from a deployment tool, the stack will clone the codebase and "play" a given deploy playbook from there.
 
 <!--TOC-->

docs/roles/cache_clear/cache_clear-opcache.md

@@ -14,7 +14,7 @@ cache_clear_opcache:
   # eg.
   # --fcgi=127.0.0.1:9000
   # Leave blank to use /etc/cachetool.yml
-  adapter: ""
+  # adapter: "127.0.0.1:9081" # Leave commented to automatically detect the adapter based on PHP version.
   # Bins to clear.
   clear_opcache: true
   clear_apcu: false

docs/roles/cli/cachetool.md

@@ -5,7 +5,8 @@ Installs the `drush` command-line tool for the deploy user.
 ```yaml
 ---
 cachetool:
-  version: latest # # enter three-digit version number, e.g. "7.0.0", to install a specific version
+  version: "" # enter three-digit version number, e.g. "7.0.0", to install a specific version. If not specified, will be installed depending on the php version.
+
 ```
 
 <!--ENDROLEVARS-->

docs/roles/deploy_code.md

@@ -37,7 +37,7 @@ With this method the live code directory is also the build directory, therefore
 ## `squashfs` builds
 Because `tarball` is very slow, we have a second method using [`squashfs`](https://github.com/plougher/squashfs-tools). This filesystem is designed for packing and compressing files into read-only images - initially to deploy to removable media - that can simply be mounted, similar to a macOS Apple Disk Image (DWG) file. It is both faster to pack than a tarball *and* instant to deploy (it's just a `mount` command).
 
-However, the build process is more complex. Because mounted `squashfs` images are read only, we cannot build over them as we do in other types of build. [We alter the build path variables in the `_init` role](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/_init/tasks/main.yml#L25) so the build happens in a separate place and then in the `cleanup.yml` we pack the built code into an image ready to be deployed. Again, because the images are read-only mounts, the live site needs to be *unmounted* with an `umount` command and then remounted with a `mount` command to be completely deployed. This requires the `ce-deploy` user to have extra `sudo` permissions, which is handled by [the `mount_sync` role in `ce-provision`](https://github.com/codeenigma/ce-provision/tree/1.x/roles/mount_sync)
+However, the build process is more complex. Because mounted `squashfs` images are read only, we cannot build over them as we do in other types of build. [We alter the build path variables in the `_init` role](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/_init/tasks/main.yml#L25) so the build happens in a separate place and then in the `cleanup.yml` we pack the built code into an image ready to be deployed. Again, because the images are read-only mounts, the live site needs to be *unmounted* with an `umount` command and then remounted with a `mount` command to be completely deployed. This requires the `ce-deploy` user to have extra `sudo` permissions, which is handled by [the `squashfs` role in `ce-provision`](https://github.com/codeenigma/ce-provision/tree/1.x/roles/squashfs).
 
 Consequently, at the build stage there are two important extra variables to set:
 
@@ -63,10 +63,10 @@ deploy_code:
 
 `service_action` is whether `ce-deploy` should restart the services in the list of stop them, unmount and remount the image and start them again. The latter is the only "safe" way to deploy, but results in a second or two of down time.
 
-Finally, as with the `tarball` method, the packed image is copied up to the NAS to be available to all future servers and is always named `deploy.sqsh`. The previous codebase is *also* packed and copied to the NAS, named `deploy_previous.sqsh` in the same directory.
+Finally, as with the `tarball` method, the packed image is copied up to the NAS to be available to all future servers and is named `PROJECTNAME_BUILDTYPE_deploy.sqsh`. [See the code here.](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/deploy_code/tasks/cleanup.yml#L80) The previous codebase is *also* packed and copied to the NAS, named `PROJECTNAME_BUILDTYPE_deploy_previous.sqsh` in the same directory.
 
 ### Rolling back
-Rolling back from a bad `squashfs` build means copying `deploy_previous.sqsh` down from the NAS to a sensible location in the `ce-deploy` user's home directory, unmounting the current image and mounting `deploy_previous.sqsh` in its place. Once you've done that, to ensure future autoscaling events do not load the bad code, on the NAS you will need to rename `deploy.sqsh` to something else (or delete it entirely if you're sure you don't want it) and rename `deploy_previous.sqsh` as `deploy.sqsh`, so it is used on an autoscale event.
+Rolling back from a bad `squashfs` build means copying the project/branch specific `deploy_previous.sqsh` down from the NAS to a sensible location in the `ce-deploy` user's home directory, unmounting the current image and mounting the `deploy_previous.sqsh` in its place. Once you've done that, to ensure future autoscaling events do not load the bad code, on the NAS you will need to rename `deploy.sqsh` to something else (or delete it entirely if you're sure you don't want it) and rename your `deploy_previous.sqsh` as `PROJECTNAME_BUILDTYPE_deploy.sqsh`, so it is used on an autoscale event. [You can see the actual code that runs on autoscale events here.](https://github.com/codeenigma/ce-provision/blob/1.x/roles/mount_sync/templates/init-squashfs.sh.j2)
 
 Same as with the `tarball` method, as long as the `database_backup` is using the `rolling` method then the "roll back" database will still exist and the credentials will be correct in the `deploy_previous.sqsh` image. Again, if the backup method is `dump` then you will need to inspect [the `mysql_backup.dumps_directory` variable](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/database_backup/database_backup-mysql/defaults/main.yml#L4) to see where the backup was saved in order to restore it.
 

roles/cache_clear/cache_clear-opcache/README.md

@@ -14,7 +14,7 @@ cache_clear_opcache:
   # eg.
   # --fcgi=127.0.0.1:9000
   # Leave blank to use /etc/cachetool.yml
-  adapter: ""
+  # adapter: "127.0.0.1:9081" # Leave commented to automatically detect the adapter based on PHP version.
   # Bins to clear.
   clear_opcache: true
   clear_apcu: false

roles/cli/cachetool/README.md

@@ -5,7 +5,8 @@ Installs the `drush` command-line tool for the deploy user.
 ```yaml
 ---
 cachetool:
-  version: latest # # enter three-digit version number, e.g. "7.0.0", to install a specific version
+  version: "" # enter three-digit version number, e.g. "7.0.0", to install a specific version. If not specified, will be installed depending on the php version.
+
 ```
 
 <!--ENDROLEVARS-->

roles/deploy_code/README.md

@@ -37,7 +37,7 @@ With this method the live code directory is also the build directory, therefore
 ## `squashfs` builds
 Because `tarball` is very slow, we have a second method using [`squashfs`](https://github.com/plougher/squashfs-tools). This filesystem is designed for packing and compressing files into read-only images - initially to deploy to removable media - that can simply be mounted, similar to a macOS Apple Disk Image (DWG) file. It is both faster to pack than a tarball *and* instant to deploy (it's just a `mount` command).
 
-However, the build process is more complex. Because mounted `squashfs` images are read only, we cannot build over them as we do in other types of build. [We alter the build path variables in the `_init` role](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/_init/tasks/main.yml#L25) so the build happens in a separate place and then in the `cleanup.yml` we pack the built code into an image ready to be deployed. Again, because the images are read-only mounts, the live site needs to be *unmounted* with an `umount` command and then remounted with a `mount` command to be completely deployed. This requires the `ce-deploy` user to have extra `sudo` permissions, which is handled by [the `mount_sync` role in `ce-provision`](https://github.com/codeenigma/ce-provision/tree/1.x/roles/mount_sync)
+However, the build process is more complex. Because mounted `squashfs` images are read only, we cannot build over them as we do in other types of build. [We alter the build path variables in the `_init` role](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/_init/tasks/main.yml#L25) so the build happens in a separate place and then in the `cleanup.yml` we pack the built code into an image ready to be deployed. Again, because the images are read-only mounts, the live site needs to be *unmounted* with an `umount` command and then remounted with a `mount` command to be completely deployed. This requires the `ce-deploy` user to have extra `sudo` permissions, which is handled by [the `squashfs` role in `ce-provision`](https://github.com/codeenigma/ce-provision/tree/1.x/roles/squashfs).
 
 Consequently, at the build stage there are two important extra variables to set:
 
@@ -63,10 +63,10 @@ deploy_code:
 
 `service_action` is whether `ce-deploy` should restart the services in the list of stop them, unmount and remount the image and start them again. The latter is the only "safe" way to deploy, but results in a second or two of down time.
 
-Finally, as with the `tarball` method, the packed image is copied up to the NAS to be available to all future servers and is always named `deploy.sqsh`. The previous codebase is *also* packed and copied to the NAS, named `deploy_previous.sqsh` in the same directory.
+Finally, as with the `tarball` method, the packed image is copied up to the NAS to be available to all future servers and is named `PROJECTNAME_BUILDTYPE_deploy.sqsh`. [See the code here.](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/deploy_code/tasks/cleanup.yml#L80) The previous codebase is *also* packed and copied to the NAS, named `PROJECTNAME_BUILDTYPE_deploy_previous.sqsh` in the same directory.
 
 ### Rolling back
-Rolling back from a bad `squashfs` build means copying `deploy_previous.sqsh` down from the NAS to a sensible location in the `ce-deploy` user's home directory, unmounting the current image and mounting `deploy_previous.sqsh` in its place. Once you've done that, to ensure future autoscaling events do not load the bad code, on the NAS you will need to rename `deploy.sqsh` to something else (or delete it entirely if you're sure you don't want it) and rename `deploy_previous.sqsh` as `deploy.sqsh`, so it is used on an autoscale event.
+Rolling back from a bad `squashfs` build means copying the project/branch specific `deploy_previous.sqsh` down from the NAS to a sensible location in the `ce-deploy` user's home directory, unmounting the current image and mounting the `deploy_previous.sqsh` in its place. Once you've done that, to ensure future autoscaling events do not load the bad code, on the NAS you will need to rename `deploy.sqsh` to something else (or delete it entirely if you're sure you don't want it) and rename your `deploy_previous.sqsh` as `PROJECTNAME_BUILDTYPE_deploy.sqsh`, so it is used on an autoscale event. [You can see the actual code that runs on autoscale events here.](https://github.com/codeenigma/ce-provision/blob/1.x/roles/mount_sync/templates/init-squashfs.sh.j2)
 
 Same as with the `tarball` method, as long as the `database_backup` is using the `rolling` method then the "roll back" database will still exist and the credentials will be correct in the `deploy_previous.sqsh` image. Again, if the backup method is `dump` then you will need to inspect [the `mysql_backup.dumps_directory` variable](https://github.com/codeenigma/ce-deploy/blob/1.x/roles/database_backup/database_backup-mysql/defaults/main.yml#L4) to see where the backup was saved in order to restore it.
 

roles/sanitize/admin_creds/admin_creds-drupal7/tasks/admin.yml

@@ -1,11 +1,14 @@
 ---
-
-- set_fact:
+- ansible.builtin.set_fact:
     _admin_user: "{{ lookup('password', '/tmp/{{ project_name }}-{{ site.folder }}-{{ build_type }}-{{ build_number }}-user chars=ascii_letters') }}"
-- set_fact:
+- ansible.builtin.set_fact:
     _admin_pwd: "{{ lookup('password', '/tmp/{{ project_name }}-{{ site.folder }}-{{ build_type }}-{{ build_number }}-pwd chars=ascii_letters') }}"
 
 - name: Reset admin username.
-  shell: "cd {{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }} && {{ drush_bin }} -l {{ site.folder }} sql-query \"UPDATE users SET name='{{ _admin_user }}' WHERE uid=1;\""
+  ansible.builtin.command:
+    cmd: "{{ drush_bin }} -l {{ site.folder }} sql-query \"UPDATE users SET name='{{ _admin_user }}' WHERE uid=1;\""
+    chdir: "{{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }}"
 - name: Reset admin password.
-  shell: "cd {{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }} && {{ drush_bin }} -l {{ site.folder }} upwd {{ _admin_user }} --password='{{ _admin_pwd }}'"
+  ansible.builtin.command:
+    cmd: "{{ drush_bin }} -l {{ site.folder }} upwd {{ _admin_user }} --password='{{ _admin_pwd }}'"
+    chdir: "{{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }}"

roles/sanitize/admin_creds/admin_creds-drupal8/tasks/admin.yml

@@ -1,16 +1,16 @@
 ---
 # For some unknown reason, updating the field_user_data table did not work reliably,
 # nor did drush upwd for the password.
-# Loading the user directly is akward, but at least means we don't bypass entity update.
+# Loading the user directly is awkward, but at least means we don't bypass entity update.
 - name: Reset admin username.
-  command:
+  ansible.builtin.command:
     cmd: "{{ drush_bin }} -l {{ site.folder }} php-eval '$admin = \\Drupal\\user\\Entity\\User::load(1); $admin->setUsername(\"{{ admin_creds.username }}\");$admin->save();' "
     chdir: "{{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }}"
   when:
     - admin_creds.username | length > 1
 
 - name: Reset admin password.
-  command:
+  ansible.builtin.command:
     cmd: "{{ drush_bin }} -l {{ site.folder }} php-eval '$admin = \\Drupal\\user\\Entity\\User::load(1); $admin->setPassword(\"{{ admin_creds.password }}\");$admin->save();' "
     chdir: "{{ deploy_path }}/{{ webroot }}/sites/{{ site.folder }}"
   when: