README.md: Add notes about the maintenance mode, with some examples

docs/maintenance.txt: Add the documentation for the maintenance mode with example on how to plug it into another role.

README.md

@@ -80,6 +80,27 @@ The opendkim DNS data has to be added to DNS manually. The roles verifies that t
 
 The file that has to be added to the zone is `/etc/opendkim/private/$selector.txt`.
 
+### Putting a service in maintenance mode
+
+Most web services with a nginx configuration, can be put into a maintenance mode, by running the playbook with a maintenance variable:
+
+    ansible-playbook -e maintenance=true playbooks/<playbook.yml>
+
+This also works with a tag:
+
+    ansible-playbook -t <tag> -e maintenance=true playbooks/<playbook.yml>
+
+As long as you pass the maintenance variable to the playbook run, the web service will stay in maintenance mode. As soon as you stop
+passing it on the command line and run the playbook again, the regular nginx configuration should resume and the service should accept
+requests by the end of the run.
+
+Passing maintenance=false, will also prevent the regular nginx configuration from resuming, but will not put the service into maintence
+mode.
+
+Keep in mind that passing the maintenance variable to the whole playbook, without any tag, will make all the web services that have the
+maintenance mode in them, to be put in maintenance mode. Use tags to affect only the services you want.
+
+Documentation on how to add the maintenance mode to a web service is inside docs/maintenance.txt
 
 ### Finding servers requiring security updates
 

docs/maintenance.txt

+# About the maintenance role
+
+The maintenance role is a generic role that contains a maintenance nginx configuration
+and a html file that is used for the 503 return.
+
+It can be plugged into any role that has a web service that uses nginx. Also, if the role
+has any alternate domains, they can also be passed to the maintenance mode and all of them
+will be redirecting to the main domain in maintenance mode.
+
+This mode works only while there is a `maintenance` variable defined. To prevent accidents,
+the variable must be explicitly defined on the command line when running a playbook with the
+-e command flag.
+
+# Adding the maintenance role to another role
+
+This role plugs into another role in two points. The first being the actual role configuration
+using ansible's include_role module. The second point is where the role receiving the maintenance
+mode configures nginx. There are a few examples of roles that can be used, like archweb and archwiki.
+
+The basic configuration looks like this:
+
+- name: run maintenance mode
+  include_role:
+    name: maintenance
+  vars:
+    service_name: "<service name>"
+    service_domain: "{{ service_domain }}"
+    service_alternate_domains: []
+    service_nginx_conf: "{{ service_nginx_conf }}"
+  when: maintenance is defined
+
+This is best placed at the top of the tasks main file for the role, to make sure it is ran first.
+Replace <service_name> with the name of the web service. The nginx configuration is best to be set
+as a variable, to make sure the right file is used.
+
+- name: set up nginx
+  template: src=nginx.d.conf.j2 dest="{{ service_nginx_conf }}" owner=root group=root mode=644
+  notify:
+    - reload nginx
+  when: maintenance is not defined
+  tags: ['nginx']
+
+This causes the regular nginx configuration to only be applied when there is no maintenance variable
+on the command line.