Merge pull request #2249 from holta/target-bits

Apache & NGINX made more readable. Add roles/www_back_end (in Stage 3 for now) & roles/www_front_end (in Stage 4 for now)

roles/0-DEPRECATED-ROLES/homepage/tasks/main.yml

@@ -0,0 +1,21 @@
+- name: Create dir {{ doc_root }}/home
+  file:
+    state: directory
+    path: "{{ doc_root }}/home"    # /library/www/html
+    owner: "{{ apache_user }}"
+    group: "{{ apache_user }}"
+    mode: '0755'
+
+- name: Install /etc/{{ apache_conf_dir }}/iiab-homepage.conf from template, for http://box redirect to http://box/home/
+  template:
+    src: iiab-homepage.conf
+    dest: "/etc/{{ apache_conf_dir }}/iiab-homepage.conf"
+
+#- name: Symlink /etc/apache2/sites-enabled/iiab-homepage.conf to /etc/{{ apache_conf_dir }}/iiab-homepage.conf (debuntu)
+- name: Enable iiab-homepage.conf via Apache
+  command: a2ensite iiab-homepage.conf
+  # file:
+  #   src: "/etc/{{ apache_conf_dir }}/iiab-homepage.conf"
+  #   path: /etc/apache2/sites-enabled/iiab-homepage.conf
+  #   state: link
+  # when: is_debuntu | bool

roles/3-base-server/tasks/main.yml

@@ -3,21 +3,28 @@
 - name: ...IS BEGINNING =====================================
   command: echo
 
-- name: HTTPD (APACHE)
-  include_role:
-    name: httpd
-  when: apache_install | bool
-
 - name: MYSQL
   include_role:
     name: mysql
   when: mysql_install | bool
 
-- name: Install NGINX (configured LATER, in Stage 9-LOCAL-ADDONS)
-  include_tasks: roles/nginx/tasks/install.yml
+- name: WWW_BACK_END (WWW_FRONT_END should be installed later)
+  include_role:
+    name: www_back_end
+  #when: www_back_end_install | bool
+  #when: apache_install or nginx_install
+
+- name: HTTPD (Apache)
+  include_role:
+    name: httpd
+  when: apache_install | bool
+
+- name: NGINX
+  include_role:
+    name: nginx
   when: nginx_install | bool
 
-- name: Install dnsmasq
+- name: dnsmasq (install now, configure LATER in 'network', after Stage 9)
   include_tasks: roles/network/tasks/dnsmasq.yml
   when: dnsmasq_install | bool
 

roles/4-server-options/tasks/main.yml

@@ -20,33 +20,33 @@
 - name: Install Bluetooth - only on Raspberry Pi
   include_role:
     name: bluetooth
-  when: is_rpi and bluetooth_install    # or bluetooth_installed is defined
+  when: is_rpi and bluetooth_install
 
 - name: USB_LIB
   include_role:
     name: usb_lib
   when: usb_lib_install | bool
 
-# This is in Stage 4-SERVER-OPTIONS (rather than 3-BASE-SERVER) because var
-# iiab_home_url changes, and may need to be re-run in the field/offline/etc.
-- name: HOMEPAGE
-  include_role:
-    name: homepage
-  # has no "when: XXXXX_install" flag
-
 - name: CUPS
   include_role:
     name: cups
-  when: cups_install    # or cups_installed is defined
+  when: cups_install | bool
 
 - name: SAMBA
   include_role:
     name: samba
-  when: samba_install    # or samba_installed is defined
+  when: samba_install | bool
 
-- name: Run /usr/bin/iiab-refresh-wiki-docs (scraper script) to create http://box/info offline documentation.  (This script was installed at the beginning of Stage 3 = roles/3-base-server/tasks/main.yml, which ran Apache playbook = roles/httpd/tasks/main.yml)
-  command: /usr/bin/iiab-refresh-wiki-docs
-  when: internet_available and not nodocs
+# 2020-02-12: what was roles/homepage lives in roles/www_back_end &
+# roles/www_front_end for now.  Eventually softcoding of iiab_home_url
+# should happen everywhere (incl Admin Console) to allow more field
+# options, e.g. changing /library/www/html/home even when offline...
+
+- name: WWW_FRONT_END (WWW_BACK_END should have been installed earlier)
+  include_role:
+    name: www_front_end
+  #when: www_front_end_install | bool
+  #when: apache_install or nginx_install
 
 - name: Recording STAGE 4 HAS COMPLETED ==================
   lineinfile:

roles/9-local-addons/tasks/main.yml

@@ -30,24 +30,34 @@
     name: calibre-web
   when: calibreweb_install | bool
 
-# Could split these two below to Stage 10?
+# Could split these two below to Stage 10?  2020-02-12: Experimentally moving
+# stuff to roles/3-base-server, 4-server-options, roles/httpd, roles/nginx.
 
-- name: Fully Enable / Configure NGINX (already installed in Stage 3-BASE-SERVER) if 'nginx_enabled' is True
-  include_role:
-    name: nginx
-  when: nginx_enabled | bool    # WAS: nginx_install
-# If just CONFIGURING (etc) shouldn't we use one of the following instead ??
-# include_tasks: roles/nginx/tasks/setup.yml
-# include_tasks: roles/nginx/tasks/enable.yml
+# - name: "Set 'nginx_enabled: True'"
+#   set_fact:
+#     nginx_enabled: True
+#
+# - name: Fully Enable / Configure NGINX (already installed in Stage 3-BASE-SERVER) if 'nginx_enabled' is True
+#   include_role:
+#     name: nginx
+#   when: nginx_enabled | bool    # WAS: nginx_install
+# # If just CONFIGURING (etc) shouldn't we use one of the following instead ??
+# # include_tasks: roles/nginx/tasks/setup.yml
+# # include_tasks: roles/nginx/tasks/enable.yml
 
-- name: Fully Enable / Configure Apache systemd service ({{ apache_service }}) if 'apache_enabled' is True
-  include_role:
-    name: httpd-enable
-  when: apache_enabled | bool    # WAS: apache_install
-# WARNING THAT APACHE IS AUTO-ENABLED BY THESE ~6 APPS ALONE!
-# https://github.com/holta/iiab/blob/scaff2/roles/0-init/tasks/main.yml#L40-L44
-# Summarized @ https://github.com/iiab/iiab/blob/master/roles/nginx/README.md
-# 2020-01-23: APACHE FUTURE SUMMARY QUESTIONS @ roles/httpd/tasks/main.yml
+# - name: "Set 'apache_enabled: True'"
+#   set_fact:
+#     apache_enabled: True
+#
+# - name: Fully Enable / Configure Apache systemd service ({{ apache_service }}) if 'apache_enabled' is True
+#   include_role:
+#     name: httpd
+#     #name: httpd-enable
+#   when: apache_enabled | bool    # WAS: apache_install
+# # WARNING THAT APACHE IS AUTO-ENABLED BY THESE ~6 APPS ALONE!
+# # https://github.com/holta/iiab/blob/scaff2/roles/0-init/tasks/main.yml#L40-L44
+# # Summarized @ https://github.com/iiab/iiab/blob/master/roles/nginx/README.md
+# # 2020-01-23: APACHE FUTURE SUMMARY QUESTIONS @ roles/httpd/tasks/main.yml
 
 - name: Recording STAGE 9 HAS COMPLETED ====================
   lineinfile:

roles/homepage/tasks/main.yml

@@ -1,19 +0,0 @@
-- name: Create dir {{ doc_root }}/home
-  file:
-    path: "{{ doc_root }}/home"
-    owner: "{{ apache_user }}"
-    group: "{{ apache_user }}"
-    mode: 0755
-    state: directory
-
-- name: Install /etc/{{ apache_conf_dir }}/iiab-homepage.conf from template, for http://box redirect to http://box/home/
-  template:
-    src: iiab-homepage.conf
-    dest: "/etc/{{ apache_conf_dir }}/iiab-homepage.conf"
-
-- name: Symlink /etc/apache2/sites-enabled/iiab-homepage.conf to /etc/{{ apache_conf_dir }}/iiab-homepage.conf (debuntu)
-  file:
-    src: "/etc/{{ apache_conf_dir }}/iiab-homepage.conf"
-    path: /etc/apache2/sites-enabled/iiab-homepage.conf
-    state: link
-  when: is_debuntu | bool

roles/httpd/tasks/enable.yml

@@ -1,69 +0,0 @@
-# For schools that use WordPress/Nextcloud/Moodle intensively.  iiab/iiab#1147
-# WARNING: Enabling this might cause excess use of RAM/disk or other resources!
-- name: Enact high limits in /etc/php/{{ php_version }}/{{ apache_service }}/php.ini if using WordPress/Nextcloud/Moodle intensively
-  lineinfile:
-    path: "/etc/php/{{ php_version }}/{{ apache_service }}/php.ini"
-    regexp: "{{ item.regexp }}"
-    line: "{{ item.line }}"
-  when: apache_high_php_limits | bool
-  with_items:
-    - { regexp: '^upload_max_filesize', line: 'upload_max_filesize = 500M    ; default is 2M' }
-    - { regexp: '^post_max_size', line: 'post_max_size = 500M    ; default is 8M' }
-    - { regexp: '^memory_limit', line: 'memory_limit = 256M    ; default is 128M / Nextcloud requests 512M' }
-    - { regexp: '^max_execution_time', line: 'max_execution_time = 300    ; default is 30' }
-    - { regexp: '^max_input_time', line: 'max_input_time = 300    ; default is 60' }
-
-- name: Install Apache's 010-iiab.conf & proxy_ajp.conf into /etc/apache2/sites-available, from templates
-  template:
-    src: "{{ item.src }}"
-    dest: "{{ item.dest }}"
-    # owner: root
-    # group: root
-    # mode: 0644
-  with_items:
-    - { src: 'roles/httpd/templates/010-iiab.conf.j2', dest: '/etc/{{ apache_conf_dir }}/010-iiab.conf' }
-    - { src: 'roles/httpd/templates/proxy_ajp.conf.j2', dest: '/etc/{{ apache_conf_dir }}/proxy_ajp.conf' }
-
-- name: Enable our site, creating 010-iiab.conf symlink from sites-enabled to sites-available (debuntu)
-  file:
-    src: "/etc/{{ apache_conf_dir }}/010-iiab.conf"
-    path: /etc/apache2/sites-enabled/010-iiab.conf
-    state: link
-  when: is_debuntu | bool
-
-# SEE https://github.com/iiab/iiab/issues/1143 as the old roles/osm playbook is rarely used as of late 2018 (if anybody still uses roles/osm, they can overwrite osm.conf using the original osm playbook, or in other ways)
-- name: Install /etc/{{ apache_conf_dir }}/osm.conf for http://box/maps (all OS's)
-  copy:
-    src: roles/httpd/files/osm.conf
-    dest: "/etc/{{ apache_conf_dir }}"
-    # owner: root
-    # group: root
-    # mode: 0644
-  when: osm_vector_maps_install | bool
-
-- name: Symlink /etc/apache2/sites-enabled/osm.conf -> /etc/{{ apache_conf_dir }}/osm.conf (debuntu)
-  file:
-    src: "/etc/{{ apache_conf_dir }}/osm.conf"
-    path: /etc/apache2/sites-enabled/osm.conf
-    state: link
-  when: is_debuntu and osm_vector_maps_enabled
-
-- name: Give {{ apache_user }} (per variable apache_user) permission to poweroff, installing /etc/sudoers.d/020_apache_poweroff from template
-  template:
-    src: roles/httpd/templates/020_apache_poweroff.j2
-    dest: /etc/sudoers.d/020_apache_poweroff
-    mode: 0755
-  when: apache_allow_sudo | bool
-
-- name: Remove {{ apache_user }} (per variable apache_user) permission to poweroff, removing /etc/sudoers.d/020_apache_poweroff
-  file:
-    path: /etc/sudoers.d/020_apache_poweroff
-    state: absent
-  when: not apache_allow_sudo
-
-- name: Restart Apache systemd service ({{ apache_service }})
-  systemd:
-    name: "{{ apache_service }}"
-    state: restarted
-    enabled: yes
-    daemon_reload: yes

roles/httpd/tasks/homepage.yml

@@ -0,0 +1,17 @@
+# Both invoked in 4-SERVER-OPTIONS, by roles/www_front_end/tasks/main.yml:
+#
+# httpd/tasks/homepage.yml
+# nginx/tasks/homepage.yml
+
+- name: Install /etc/{{ apache_conf_dir }}/iiab-homepage.conf from httpd/templates, so Apache redirects http://box to http://box{{ iiab_home_url }}    # /home
+  template:
+    src: roles/httpd/templates/iiab-homepage.conf
+    dest: "/etc/{{ apache_conf_dir }}/iiab-homepage.conf"    # apache2/sites-available (on debuntu)
+
+- name: "IN CASE NGINX IS DISABLED: Enable IIAB pages via Apache (e.g. on port 80) by running 'a2ensite iiab-homepage.conf'"
+  command: a2ensite iiab-homepage.conf
+  #when: apache_enabled | bool
+
+# - name: Disable IIAB pages via Apache (e.g. on port 80) by running 'a2dissite iiab-homepage.conf', if not apache_enabled"
+#   command: a2dissite iiab-homepage.conf
+#   when: not apache_enabled

roles/httpd/tasks/html.yml

@@ -1,68 +0,0 @@
-- name: Copy css files to {{ doc_root }}/common/css    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/css"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/css/*.css
-
-- name: Copy js files to {{ doc_root }}/common/js    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/js"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/js/*.js
-
-- name: Copy fonts files to {{ doc_root }}/common/fonts    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/fonts"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/fonts/*
-
-- name: Copy html files to {{ doc_root }}/common/html    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/html"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/html/*
-
-- name: Copy assets files to {{ doc_root }}/common/assets    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/assets"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/assets/*
-
-# copy all services, even if not permissioned elsewhere
-- name: Copy services files to {{ doc_root }}/common/services    # doc_root is /library/www/html
-  copy:
-    src: "{{ item }}"
-    dest: "{{ doc_root }}/common/services"
-    mode: 0644
-    owner: root
-    group: root
-  with_fileglob:
-    - html/services/*
-
-- name: Symlink {{ doc_root }}/common/assets/iiab.ini to {{ iiab_ini_file }}    # doc_root is /library/www/html
-  file:
-    src: "{{ iiab_ini_file }}"
-    path: "{{ doc_root }}/common/assets/iiab.ini"
-    owner: root
-    group: root
-    state: link

roles/httpd/tasks/install.yml

@@ -49,7 +49,7 @@
     state: present
   when: is_redhat | bool
 
-# remove symlinks for mpm-event, replace with mpm-prefork
+# Remove symlinks for mpm_event, replace with mpm_prefork
 - name: Remove both mpm_event symlinks from /etc/apache2/mods-enabled (debuntu)
   file:
     path: "/etc/apache2/mods-enabled/{{ item }}"
@@ -69,6 +69,19 @@
     - mpm_prefork.load
   when: is_debuntu | bool
 
+# - name: Remove mpm_event.conf & mpm_event.load symlinks, using a2dissite
+#   command: "a2dissite {{ item }}"
+#   with_items:
+#     - mpm_event.conf
+#     - mpm_event.load
+#   ignore_errors: yes
+#
+# - name: Symlink mpm_prefork.conf & mpm_prefork.load, using a2ensite
+#   command: "a2ensite {{ item }}"
+#   with_items:
+#     - mpm_prefork.conf
+#     - mpm_prefork.load
+
 #- name: 'Turn on mod_proxy using a2enmod with: proxy, proxy_html, headers, rewrite (debuntu)'
 #  command: a2enmod {{ item }}
 #  with_items:
@@ -100,11 +113,11 @@
 
 - name: Create Apache's pid dir /var/run/{{ apache_user }}
   file:
+    state: directory
     path: "/var/run/{{ apache_user }}"
     owner: root
     group: root
     mode: '0755'
-    state: directory
 
 - name: 'Create group: admin'
   group:
@@ -120,25 +133,38 @@
 
 - name: Create Apache dir /var/log/{{ apache_service }}
   file:
+    state: directory
     path: "/var/log/{{ apache_service }}"
     owner: "{{ apache_user }}"
     group: "{{ apache_user }}"
     mode: '0755'
-    state: directory
 
-- name: Enable Apache systemd service ({{ apache_service }})
-  service:
-    name: "{{ apache_service }}"
-    enabled: yes
-    state: stopped
 
-- name: Create /library/www/html/info directory for http://box/info offline docs
-  file:
-    path: "{{ doc_root }}/info"
-    owner: "{{ apache_user }}"
-    group: "{{ apache_user }}"
-    mode: '0755'
-    state: directory
+- name: Install Apache's 010-iiab.conf & proxy_ajp.conf into /etc/apache2/sites-available, from templates
+  template:
+    src: "{{ item.src }}"
+    dest: "{{ item.dest }}"
+  with_items:
+    - { src: 'roles/httpd/templates/010-iiab.conf.j2', dest: '/etc/{{ apache_conf_dir }}/010-iiab.conf' }
+    - { src: 'roles/httpd/templates/proxy_ajp.conf.j2', dest: '/etc/{{ apache_conf_dir }}/proxy_ajp.conf' }
+
+- name: "IN CASE NGINX IS DISABLED: Enable IIAB pages via Apache (e.g. on port 80) by running 'a2ensite 010-iiab.conf'"
+  command: a2ensite 010-iiab.conf
+  #when: apache_enabled | bool
+
+# - name: Disable IIAB pages via Apache (e.g. on port 80) by running 'a2dissite 010-iiab.conf', if not apache_enabled"
+#   command: a2dissite 010-iiab.conf
+#   when: not apache_enabled
+
+- debug:
+    msg: roles/httpd/tasks/homepage.yml will run LATER (invoked by roles/www_front_end/tasks/main.yml) SO THAT APACHE CAN REDIRECT http://box TO http://box{{ iiab_home_url }} (based on var iiab_home_url)
+# - include_tasks: roles/httpd/tasks/homepage.yml
+
+# - name: Enable & Stop '{{ apache_service }}' systemd service
+#   systemd:
+#     name: "{{ apache_service }}"
+#     enabled: yes
+#     state: stopped
 
 
 # RECORD Apache AS INSTALLED

roles/httpd/tasks/main.yml

@@ -1,20 +1,64 @@
-# 2020-01-23 TO DO / Questions:
-# - Validate input vars apache_install & apache_enabled here.
-#   - Use as nec, with 'when: apache_installed is undefined'
-# - Encapsulate all 3 tasks below into httpd/roles/install.yml ?
-# - Similarly sanity-check httpd/roles/enable.yml or httpd/roles/enable-or-disable.yml...
-#   - Verify that 9-local-addons/tasks/main.yml's invocation of
-#     roles/httpd/tasks/enable.yml (via roles/httpd-enable/tasks/main.yml, if
-#     apache_enabled is True) does the right thing!
-#   - And that we really don't want to invoke it hereunder?
-# - Save relevant apache_* vars to /etc/iiab/iiab.ini
+# "How do i fail a task in Ansible if the variable contains a boolean value?
+# I want to perform input validation for Ansible playbooks"
+# https://stackoverflow.com/questions/46664127/how-do-i-fail-a-task-in-ansible-if-the-variable-contains-a-boolean-value-i-want/46667499#46667499
 
-- include_tasks: install.yml
-- include_tasks: html.yml
-- include_tasks: php-stem.yml
+# We assume 0-init/tasks/validate_vars.yml has DEFINITELY been run, so no need
+# to re-check whether vars are defined here.  As Ansible vars cannot be unset:
+# https://serverfault.com/questions/856729/how-to-destroy-delete-unset-a-variable-value-in-ansible
 
-- name: Install /usr/bin/iiab-refresh-wiki-docs (scraper script) to create http://box/info offline documentation.  (Script can be run manually and/or at the end of Stage 4 = roles/4-server-options/tasks/main.yml)
-  template:
-    src: refresh-wiki-docs.sh
-    dest: /usr/bin/iiab-refresh-wiki-docs
-    mode: '0755'
+- name: Assert that "apache_install is sameas true" (boolean not string etc)
+  assert:
+    that: apache_install is sameas true
+    fail_msg: "PLEASE SET 'apache_install: True' e.g. IN: /etc/iiab/local_vars.yml"
+    quiet: yes
+
+- name: Assert that "apache_enabled | type_debug == 'bool'" (boolean not string etc)
+  assert:
+    that: apache_enabled | type_debug == 'bool'
+    fail_msg: "PLEASE GIVE VARIABLE 'apache_enabled' A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
+    quiet: yes
+
+- debug:
+    var: apache_install
+- debug:
+    var: apache_enabled
+- debug:
+    var: apache_installed
+
+
+- name: Install Apache if 'apache_installed' not defined, e.g. in {{ iiab_state_file }}    # /etc/iiab/iiab_state.yml
+  include_tasks: install.yml
+  when: apache_installed is undefined
+
+
+- name: Enable & (Re)Start {{ apache_service }} systemd service, if apache_enabled
+  systemd:
+    name: "{{ apache_service }}"
+    daemon_reload: yes
+    enabled: yes
+    state: restarted
+  when: apache_enabled | bool
+
+- name: Disable & Stop {{ apache_service }} systemd service, if not apache_enabled
+  systemd:
+    name: "{{ apache_service }}"
+    enabled: no
+    state: stopped
+  when: not apache_enabled
+
+
+- name: Add 'apache' variable values to {{ iiab_ini_file }}
+  ini_file:
+    path: "{{ iiab_ini_file }}"    # /etc/iiab/iiab.ini
+    section: apache
+    option: "{{ item.option }}"
+    value: "{{ item.value | string }}"
+  with_items:
+    - option: name
+      value: Apache
+    - option: description
+      value: '"The Apache HTTP Server (''httpd'')."'
+    - option: apache_install
+      value: "{{ apache_install }}"
+    - option: apache_enabled
+      value: "{{ apache_enabled }}"

roles/httpd/templates/iiab-homepage.conf

@@ -0,0 +1,9 @@
+# IIAB Home Page
+
+# Redirect to home page on School Server
+# Default [was] xs-portal [and is now generally] home
+
+# RedirectMatch of root to homepage
+# See the note in default_vars.yml
+
+RedirectMatch ^/$ {{ iiab_home_url }}

roles/internetarchive/tasks/install.yml

@@ -41,7 +41,7 @@
     state: absent
     path: "{{ internetarchive_dir }}/node_modules"
 
-- name: Run 'yarn add @internetarchive/dweb-mirror' to download/populate {{ internetarchive_dir }}/node_modules (CAN TAKE ~15 MINUTES)
+- name: Run 'yarn add @internetarchive/dweb-mirror' to download/populate {{ internetarchive_dir }}/node_modules (CAN TAKE ~5 MINUTES)
   shell: yarn config set child-concurrency 1 && yarn add @internetarchive/dweb-mirror
   args:
     chdir: "{{ internetarchive_dir }}"

roles/internetarchive/tasks/main.yml

@@ -20,7 +20,7 @@
 
 
 # 2020-02-11: @mitra42 & @holta agree (#2247) that the following 2-stanza
-# "UPDATE internetarchive" block should run whenever one is isn't installing
+# "UPDATE internetarchive" block should run whenever one isn't installing
 # (or reinstalling) internetarchive, for now.  We're aware this means slowness
 # during "./runrole internetarchive" but that's very intentional for now -- as
 # it leads to more testing of more recent versions of internetarchive, which

roles/minetest/tasks/rpi_minetest_install.yml

@@ -30,7 +30,7 @@
     owner: root
     group: root
 
-- name: Create symbolic link /library/games/minetest
+- name: Symlink /library/games/minetest -> /library/games/0.4.17.1
   file:
     state: link
     src: /library/games/0.4.17.1

roles/nginx/tasks/enable-or-disable.yml

@@ -0,0 +1,40 @@
+- name: Ensure that Apache (({{ apache_service }})) is not running -- we may need port swap
+  systemd:
+    name: "{{ apache_service }}"    # apache2 or httpd, per /opt/iiab/iiab/vars/<OS>.yml
+    state: stopped
+
+- name: Install /etc/{{ apache_service }}/ports.conf from template 1 of 2 (ports.conf.j2) if nginx_enabled, to enable Apache port {{ apache_port }} localhost only
+  template:
+    src: ports.conf.j2
+    dest: "/etc/{{ apache_service }}/ports.conf"
+  when: nginx_enabled | bool
+
+- name: Install /etc/{{ apache_service }}/ports.conf from template 2 of 2 (stock-apache-ports.conf) if not nginx_enabled, to disable Apache port {{ apache_port }} localhost only
+  template:
+    src: stock-apache-ports.conf
+    dest: "/etc/{{ apache_service }}/ports.conf"
+  when: not nginx_enabled
+
+- name: Enable & Restart '{{ apache_service }}' if apache_enabled or not nginx_enabled, since we stopped it
+  systemd:
+    name: "{{ apache_service }}"    # apache2 or httpd, per /opt/iiab/iiab/vars/<OS>.yml
+    daemon_reload: yes
+    state: restarted
+    enabled: true
+  when: apache_enabled or not nginx_enabled
+
+
+- name: Enable & (Re)Start 'nginx' systemd service, if nginx_enabled
+  systemd:
+    name: nginx
+    daemon_reload: yes
+    enabled: yes
+    state: restarted
+  when: nginx_enabled | bool
+
+- name: Disable & Stop 'nginx' systemd service, if not nginx_enabled
+  systemd:
+    name: nginx
+    enabled: no
+    state: stopped
+  when: not nginx_enabled

roles/nginx/tasks/homepage.yml

@@ -0,0 +1,9 @@
+# Both invoked in 4-SERVER-OPTIONS, by roles/www_front_end/tasks/main.yml:
+#
+# httpd/tasks/homepage.yml
+# nginx/tasks/homepage.yml
+
+- name: Install {{ nginx_conf_dir }}/iiab.conf from nginx/templates, so NGINX redirects http://box to http://box{{ iiab_home_url }}    # /home
+  template:
+    src: roles/nginx/templates/iiab.conf.j2
+    dest: "{{ nginx_conf_dir }}/iiab.conf"    # /etc/nginx/conf.d

roles/nginx/tasks/install.yml

@@ -1,4 +1,20 @@
-- name: Install NGINX required and helper packages
+# This stanza can likely be removed later in 2020:
+- name: 'Remove legacy files if present: /etc/systemd/system/uwsgi.service, {{ nginx_conf_dir }}/usb-lib.conf, {{ nginx_conf_dir }}/modules.conf'
+  file:
+    path: "{{ item.path }}"
+    state: absent
+  with_items:
+    - { path: "/etc/systemd/system/uwsgi.service" }
+    - { path: "{{ nginx_conf_dir }}/usb-lib.conf" }
+    - { path: "{{ nginx_conf_dir }}/modules.conf" }
+
+- name: Stop '{{ apache_service }}' systemd service
+  systemd:
+    name: "{{ apache_service }}"    # apache2 or httpd, per /opt/iiab/iiab/vars/<OS>.yml
+    state: stopped
+  ignore_errors: yes
+
+- name: Install required and helper packages for NGINX
   package:
     name: "{{ item }}"
     state: present
@@ -9,9 +25,9 @@
     - php-fpm
     - libnginx-mod-http-subs-filter
 
-- name: Add http server user to shadow group, so it can authenticate Admin Console
+- name: Add user '{{ apache_user }}' to shadow group, so it can authenticate Admin Console
   user:
-    name: "{{ apache_user }}"
+    name: "{{ apache_user }}"    # www-data or apache, per /opt/iiab/iiab/vars/<OS>.yml
     groups: shadow
 
 - name: Remove NGINX default config /etc/nginx/sites-enabled/default
@@ -19,29 +35,34 @@
     path: /etc/nginx/sites-enabled/default
     state: absent
 
-- name: 'Install 4 files from template: /etc/nginx/server.conf, /etc/nginx/nginx.conf, /etc/{{ apache_service }}/ports.conf, /etc/systemd/system/uwsgi.service'
+- name: 'Install 2 (of 4) files from template: /etc/nginx/server.conf, /etc/nginx/nginx.conf'
   template:
     src: "{{ item.src }}"
     dest: "{{ item.dest }}"
   with_items:
-    - { src: 'roles/nginx/templates/server.conf.j2', dest: '/etc/nginx/server.conf' }
-    - { src: 'roles/nginx/templates/nginx.conf.j2', dest: '/etc/nginx/nginx.conf' }
-    - { src: 'roles/nginx/templates/ports.conf.j2', dest: '/etc/{{ apache_service }}/ports.conf' }
+    - { src: 'server.conf.j2', dest: '/etc/nginx/server.conf' }
+    - { src: 'nginx.conf.j2', dest: '/etc/nginx/nginx.conf' }
+    #- { src: 'ports.conf.j2', dest: '/etc/{{ apache_service }}/ports.conf' }    # Moved to enable-or-disable.yml
+    #- { src: 'iiab.conf.j2', dest: "{{ nginx_conf_dir }}/iiab.conf" }    # Moved into homepage.yml below
 
-# php stem extension is installed in role httpd
+- debug:
+    msg: roles/nginx/tasks/homepage.yml will run LATER (invoked by roles/www_front_end/tasks/main.yml) SO THAT NGINX CAN REDIRECT http://box TO http://box{{ iiab_home_url }} (based on var iiab_home_url)
+# - include_tasks: roles/nginx/tasks/homepage.yml
+
+# php-stem extension installed by roles/www_back_end/tasks/php-stem.yml
 # here it is linked to php-fpm
-- name: Create softlink 20-stem.ini to /etc/php/{{ php_version }}/mods-available/stem.ini
+- name: Symlink /etc/php/{{ php_version }}/fpm/conf.d/20-stem.ini -> /etc/php/{{ php_version }}/mods-available/stem.ini
   file:
     src: "/etc/php/{{ php_version }}/mods-available/stem.ini"
     path: "/etc/php/{{ php_version }}/fpm/conf.d/20-stem.ini"
     state: link
-  when: nginx_enabled
+  #when: nginx_enabled | bool
 
-- name: Restart php{{ php_version }}-fpm service
-  service:
+- name: Restart php{{ php_version }}-fpm systemd service
+  systemd:
     name: "php{{ php_version }}-fpm"
     state: restarted
-  when: nginx_enabled
+  #when: nginx_enabled | bool
 
 
 # RECORD NGINX AS INSTALLED

roles/nginx/tasks/main.yml

@@ -1,70 +1,51 @@
-- name: Remove stale files (usb-lib.conf, modules.conf) from {{ nginx_conf_dir }}
-  file:
-    path: "{{ item.path }}"
-    state: absent
+# "How do i fail a task in Ansible if the variable contains a boolean value?
+# I want to perform input validation for Ansible playbooks"
+# https://stackoverflow.com/questions/46664127/how-do-i-fail-a-task-in-ansible-if-the-variable-contains-a-boolean-value-i-want/46667499#46667499
+
+# We assume 0-init/tasks/validate_vars.yml has DEFINITELY been run, so no need
+# to re-check whether vars are defined here.  As Ansible vars cannot be unset:
+# https://serverfault.com/questions/856729/how-to-destroy-delete-unset-a-variable-value-in-ansible
+
+- name: Assert that "nginx_install is sameas true" (boolean not string etc)
+  assert:
+    that: nginx_install is sameas true
+    fail_msg: "PLEASE SET 'nginx_install: True' e.g. IN: /etc/iiab/local_vars.yml"
+    quiet: yes
+
+- name: Assert that "nginx_enabled | type_debug == 'bool'" (boolean not string etc)
+  assert:
+    that: nginx_enabled | type_debug == 'bool'
+    fail_msg: "PLEASE GIVE VARIABLE 'nginx_enabled' A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
+    quiet: yes
+
+- debug:
+    var: nginx_install
+- debug:
+    var: nginx_enabled
+- debug:
+    var: nginx_installed
+
+
+- name: Install NGINX if 'nginx_installed' not defined, e.g. in {{ iiab_state_file }}    # /etc/iiab/iiab_state.yml
+  include_tasks: install.yml
+  when: nginx_installed is undefined
+
+
+- include_tasks: enable-or-disable.yml
+
+
+- name: Add 'nginx' variable values to {{ iiab_ini_file }}
+  ini_file:
+    path: "{{ iiab_ini_file }}"    # /etc/iiab/iiab.ini
+    section: nginx
+    option: "{{ item.option }}"
+    value: "{{ item.value | string }}"
   with_items:
-    - { path: "/etc/systemd/system/uwsgi.service" }
-    - { path: "{{ nginx_conf_dir }}/usb-lib.conf" }
-    - { path: "{{ nginx_conf_dir }}/modules.conf" }
-
-- name: Ensure that Apache (({{ apache_service }})) is not running -- we may need port swap
-  systemd:
-    name: "{{ apache_service }}"
-    state: stopped
-
-- name: "Install from template: /etc/nginx/server.conf, /etc/nginx/nginx.conf, /etc/{{ apache_service }}/ports.conf, {{ nginx_conf_dir }}/iiab.conf"
-  template:
-    src: "{{ item.src}}"
-    dest: "{{ item.dest }}"
-  with_items:
-    - { src: 'server.conf.j2', dest: '/etc/nginx/server.conf' }
-    - { src: 'nginx.conf.j2', dest: '/etc/nginx/nginx.conf' }
-    - { src: 'ports.conf.j2', dest: "/etc/{{ apache_service }}/ports.conf" }
-    - { src: 'iiab.conf.j2', dest: "{{ nginx_conf_dir }}/iiab.conf" }
-  when: nginx_enabled | bool
-
-# the below slides in nginx's proxypass config files for apache on localhost
-# via the ports.conf file installed above
-#- name: Install proxpass to Apache running on localhost port {{ apache_port }}
-#  include_tasks: uses_apache.yml
-#  when: apache_enabled | bool
-
-# the below task contains the same logic contained in the playbooks to enable
-# 'runrole nginx' to do the right thing but with the 'src' path set to role's
-# templates path ie roles/<rolename>/template/
-#- name: Install proxpass to other services 'dual mode' roles
-#  include_tasks: only_nginx.yml
-#  when: nginx_enabled | bool
-
-- name: Stop & Disable 'nginx' systemd service, when not nginx_enabled
-  systemd:
-    name: nginx
-    state: stopped
-    enabled: false
-  when: not nginx_enabled
-
-- name: Disable Apache port {{ apache_port }} localhost only, when not nginx_enabled
-  template:
-    dest: /etc/{{ apache_service }}/ports.conf
-    src: stock-apache-ports.conf
-  when: not nginx_enabled
-
-# should have the logic to handle both modes in the playbook
-#- name: Enable Apache (a2ensite) for 'dual mode' for the role when NGINX is disabled
-#  include_tasks: disable.yml
-#  when: not nginx_enabled
-
-- name: Enable & Restart Apache, since we stopped it ({{ apache_service }})
-  systemd:
-    name: "{{ apache_service }}"
-    daemon_reload: yes
-    state: restarted
-    enabled: true
-  when: apache_enabled or not nginx_enabled
-
-- name: Enable & Restart NGINX, to pick up the config files installed
-  systemd:
-    name: nginx
-    state: restarted
-    enabled: true
-  when: nginx_enabled | bool
+    - option: name
+      value: NGINX
+    - option: description
+      value: '"NGINX is a web server which can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache."'
+    - option: nginx_install
+      value: "{{ nginx_install }}"
+    - option: nginx_enabled
+      value: "{{ nginx_enabled }}"

roles/www_back_end/tasks/html.yml

@@ -0,0 +1,68 @@
+- name: Copy css files to {{ doc_root }}/common/css
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/css"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/css/*.css
+
+- name: Copy js files to {{ doc_root }}/common/js
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/js"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/js/*.js
+
+- name: Copy fonts files to {{ doc_root }}/common/fonts
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/fonts"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/fonts/*
+
+- name: Copy html files to {{ doc_root }}/common/html
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/html"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/html/*
+
+- name: Copy assets files to {{ doc_root }}/common/assets
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/assets"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/assets/*
+
+# Copy all services, even if not permissioned elsewhere
+- name: Copy services files to {{ doc_root }}/common/services
+  copy:
+    src: "{{ item }}"
+    dest: "{{ doc_root }}/common/services"    # /library/www/html
+    # owner: root
+    # group: root
+    # mode: '0644'
+  with_fileglob:
+    - html/services/*
+
+- name: Symlink {{ doc_root }}/common/assets/iiab.ini -> {{ iiab_ini_file }}
+  file:
+    src: "{{ iiab_ini_file }}"    # /etc/iiab/iiab.ini
+    path: "{{ doc_root }}/common/assets/iiab.ini"    # /library/www/html
+    # owner: root
+    # group: root
+    state: link

roles/www_back_end/tasks/main.yml

@@ -0,0 +1,64 @@
+# Role "www_back_end" runs here, probably in 3-BASE-SERVER.
+# Role "www_front_end" runs later, likely in 4-SERVER-OPTIONS.
+#
+# (Don't take either name too literally!)
+
+
+- include_tasks: html.yml
+
+
+- include_tasks: php-stem.yml
+
+# 2020-02-12: DOES THE FLAG BELOW (apache_high_php_limits) WORK WITH NGINX TOO?
+# COMPARE apache_allow_sudo @ roles/www_front_end/tasks/main.yml
+
+# For schools that use WordPress/Nextcloud/Moodle intensively.  iiab/iiab#1147
+# WARNING: Enabling this might cause excess use of RAM/disk or other resources!
+- name: Enact high limits in /etc/php/{{ php_version }}/{{ apache_service }}/php.ini if using WordPress/Nextcloud/Moodle intensively
+  lineinfile:
+    path: "/etc/php/{{ php_version }}/{{ apache_service }}/php.ini"
+    regexp: "{{ item.regexp }}"
+    line: "{{ item.line }}"
+  when: apache_high_php_limits | bool
+  with_items:
+    - { regexp: '^upload_max_filesize', line: 'upload_max_filesize = 500M    ; default is 2M' }
+    - { regexp: '^post_max_size', line: 'post_max_size = 500M    ; default is 8M' }
+    - { regexp: '^memory_limit', line: 'memory_limit = 256M    ; default is 128M / Nextcloud requests 512M' }
+    - { regexp: '^max_execution_time', line: 'max_execution_time = 300    ; default is 30' }
+    - { regexp: '^max_input_time', line: 'max_input_time = 300    ; default is 60' }
+
+
+- name: Create dir {{ doc_root }}/home -- if you customized var iiab_home_url e.g. in /etc/iiab/local_vars.yml, that dir is created later -- by www_front_end/tasks/main.yml
+  file:
+    state: directory
+    path: "{{ doc_root }}/home"    # /library/www/html
+    owner: "{{ apache_user }}"
+    group: "{{ apache_user }}"
+    # mode: '0755'
+
+- name: Create dir {{ doc_root }}/info for http://box/info offline docs
+  file:
+    state: directory
+    path: "{{ doc_root }}/info"    # /library/www/html
+    owner: "{{ apache_user }}"
+    group: "{{ apache_user }}"
+    # mode: '0755'
+
+- name: Install /usr/bin/iiab-refresh-wiki-docs (scraper script) to create http://box/info offline documentation.  (Script can be run manually and/or at the end of Stage 4 = roles/4-server-options/tasks/main.yml)
+  template:
+    src: iiab-refresh-wiki-docs.sh
+    dest: /usr/bin/iiab-refresh-wiki-docs
+    mode: '0755'
+
+
+# RECORD www_back_end AS INSTALLED
+
+- name: "Set 'www_back_end_installed: True'"
+  set_fact:
+    www_back_end_installed: True
+
+- name: "Add 'www_back_end_installed: True' to {{ iiab_state_file }}"
+  lineinfile:
+    path: "{{ iiab_state_file }}"    # /etc/iiab/iiab_state.yml
+    regexp: '^www_back_end_installed'
+    line: 'www_back_end_installed: True'

roles/www_back_end/tasks/php-stem.yml

@@ -23,7 +23,7 @@
     remote_src: yes
   when: ansible_machine == "x86_64"
 
-# link to php done in nginx when php-fpm is installed
+# link to php done in roles/nginx/tasks/install.yml when php-fpm is installed
 
 # Not sure what to do for apache, so do nothing for now
 

roles/www_front_end/tasks/main.yml

@@ -0,0 +1,76 @@
+# Role "www_back_end" runs earlier, likely in 3-BASE-SERVER.
+# Role "www_front_end" runs here, probably in 4-SERVER-OPTIONS.
+#
+# (Don't take either name too literally!)
+
+
+# HOMEPAGE
+
+- name: Create dir {{ doc_root }}{{ iiab_home_url }} just in case variable iiab_home_url was customized.  (Standard path {{doc_root}}/home was created earlier.)
+  file:
+    state: directory
+    path: "{{ doc_root }}{{ iiab_home_url }}"    # /library/www/html/home
+    owner: "{{ apache_user }}"
+    group: "{{ apache_user }}"
+    mode: '0755'
+
+# Used to be run by httpd/tasks/install.yml
+- name: "IN CASE NGINX IS DISABLED: Enable IIAB pages via Apache (e.g. on port 80) if apache_install"
+  include_tasks: roles/httpd/tasks/homepage.yml
+  when: apache_install | bool
+
+# Used to be run by nginx/tasks/install.yml
+- name: Enable IIAB pages via NGINX (e.g. on port 80) if nginx_install
+  include_tasks: roles/nginx/tasks/homepage.yml
+  when: nginx_install | bool
+
+
+# 'Is a "Rapid Power Off" button possible for low-electricity environments?'
+# gives more details here: http://FAQ.IIAB.IO
+
+# 2020-02-12: DOES THE FLAG BELOW (apache_allow_sudo) WORK WITH NGINX TOO ?
+# COMPARE apache_high_php_limits @ roles/www_back_end/tasks/main.yml
+
+- name: Give {{ apache_user }} (per variable apache_user) permission to poweroff, installing /etc/sudoers.d/020_apache_poweroff from template
+  template:
+    src: 020_apache_poweroff.j2
+    dest: /etc/sudoers.d/020_apache_poweroff
+    mode: '0755'
+  when: apache_allow_sudo | bool
+
+- name: Remove {{ apache_user }} (per variable apache_user) permission to poweroff, removing /etc/sudoers.d/020_apache_poweroff
+  file:
+    path: /etc/sudoers.d/020_apache_poweroff
+    state: absent
+  when: not apache_allow_sudo
+
+
+- name: Run /usr/bin/iiab-refresh-wiki-docs (scraper script) to create http://box/info offline documentation.  (This script was installed in Stage 3 = roles/3-base-server/tasks/main.yml, which ran roles/www_back_end/tasks/main.yml)
+  command: /usr/bin/iiab-refresh-wiki-docs
+  when: internet_available and not nodocs
+
+
+- name: (Re)Start '{{ apache_service }}' systemd service, if apache_enabled
+  systemd:
+    name: "{{ apache_service }}"    # apache2 on debuntu
+    state: restarted
+  when: apache_enabled | bool
+
+- name: (Re)Start 'nginx' systemd service, if nginx_enabled
+  systemd:
+    name: nginx
+    state: restarted
+  when: nginx_enabled | bool
+
+
+# RECORD www_front_end AS INSTALLED
+
+- name: "Set 'www_front_end_installed: True'"
+  set_fact:
+    www_front_end_installed: True
+
+- name: "Add 'www_front_end_installed: True' to {{ iiab_state_file }}"
+  lineinfile:
+    path: "{{ iiab_state_file }}"    # /etc/iiab/iiab_state.yml
+    regexp: '^www_front_end_installed'
+    line: 'www_front_end_installed: True'

tests/test.yml

@@ -16,8 +16,12 @@
     #- { role: ajenti }
     #- { role: authserver }
     - { role: awstats }
+    - { role: azuracast }
+    - { role: bluetooth }
     - { role: calibre }
     - { role: calibre-web }
+    - { role: captiveportal }
+    #- { role: cham }
     - { role: cups }
     #- { role: debian_schooltool }
     #- { role: docker }
@@ -25,28 +29,37 @@
     #- { role: ejabberd }
     #- { role: ejabberd_xs }
     - { role: elgg }
-    - { role: homepage }
+    - { role: gitea }
+    #- { role: homepage }
     - { role: httpd }
     #- { role: idmgr }
     - { role: iiab-admin }
+    - { role: internetarchive }
     - { role: kalite }
     - { role: kiwix }
     - { role: kolibri }
     - { role: lokole }
     - { role: mediawiki }
+    - { role: minetest }
     - { role: mongodb }
     - { role: monit }
     - { role: moodle }
     #- { role: moodle-1.9 }
+    - { role: mosquitto }
     - { role: munin }
     - { role: mysql }
     - { role: network }
     - { role: nextcloud }
+    - { role: nginx }
+    - { role: nodejs }
+    - { role: nodered }
     #- { role: nodogsplash }
     - { role: openvpn }
+    - { role: osm-vector-maps }
     #- { role: osm }
     #- { role: owncloud }
     #- { role: pathagar }
+    - { role: pbx }
     - { role: phpmyadmin }
     - { role: postgresql }
     #- { role: rachel }
@@ -60,6 +73,9 @@
     - { role: usb_lib }
     - { role: vnstat }
     - { role: wordpress }
+    - { role: www_back_end }
+    - { role: www_front_end }
+    - { role: yarn }
     #- { roles: xovis }
 
 # Let's try to keep the above list synchronized with: