deploying the necessary PHP applications, while still reusing a common base and

reducing the workload.

The role implements the following:

* Creates a dedicated user/group for running the PHP scripts.

* Creates a base directory where the website-specific code and data should be

  stored at.

* Adds nginx to website's group, so nginx could read the necessary files.

* Adds website administrator to website's group, so administrator could manage

  the code and data.

* Installs additional packages required for running the role (as configured).

The role is implemented with the following layout/logic in mind:

* Website users are named after the ``FQDN`` (fully qualified domain name) of

  website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to

  ``FQDN`` where dots have been replaced by underscores (for example,

  ``web-cloud_example_com``).

* All websites reside within a dedicated sub-directory in ``/var/www``. The

  sub-directory name is equal to the ``FQDN`` used for accessing the

  website. Owner of the directory is set to be the application administrator,

  while group is set to be the website group. Additionally, ``SGID`` bit is set

  on the directory. This allows admin, with correct umask, to create necessary

  files and directories that should be readable (and eventually writeable) by

  **comment** (string, mandatory)

    Comment describing the configuration option.

  **value** (string, mandatory)

    Configuration option.

**deny_files_regex** (list, optional, ``[]``)

  List of regular expressions for matching files/locations to which the web

  server should deny access. This is useful to block access to any sensitive

  files that should not be served directly by the web server. The format must be

  compatible with regular expressions used by ``nginx`` for ``location ~``

.. code-block:: yaml

    - role: php_website

      fqdn: cloud.example.com

      uid: 2001

      php_file_regex: \.php($|/)

      rewrites:

        - ^/\.well-known/host-meta /public.php?service=host-meta

        - ^/\.well-known/host-meta\.json /public.php?service=host-meta-json

        - ^/\.well-known/carddav /remote.php/carddav/ redirect

        - ^/\.well-known/caldav /remote.php/caldav/ redirect

      additional_nginx_config:

        - comment: Use custom page for forbidden files.

          value: error_page 403 /core/templates/403.php;

        - comment: Use custom page for non-existing locations/files.

          value: error_page 404 /core/templates/404.php;

    - role: php_website

      deny_files_regex:

        - ^\..*

      php_rewrite_urls:

        - ^(.*) /index.php?url=$1

      fqdn: tbg.example.com

      uid: 2007

deploying the necessary Python applications/packages, while still reusing a

common base and reducing the workload.

The role implements the following:

* Creates a dedicated user/group for running the WSGI application.

* Creates a base directory where the website-specific code and data should be

  stored at.

* Adds nginx to website's group, so nginx could read the necessary files.

* Adds website administrator to website's group, so administrator could manage

  the code and data.

* Installs additional packages required for running the role (as configured).

The role is implemented with the following layout/logic in mind:

* Website users are named after the ``FQDN`` (fully qualified domain name) of

  website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to

  ``FQDN`` where dots have been replaced by underscores (for example,

  ``web-wiki_example_com``).

* All websites reside within a dedicated sub-directory in ``/var/www``. The

  sub-directory name is equal to the ``FQDN`` used for accessing the

  website. Owner of the directory is set to be the application administrator,

  while group is set to be the website group. Additionally, ``SGID`` bit is set

  on the directory. This allows admin, with correct umask, to create necessary

  files and directories that should be readable (and eventually writeable) by

  the website user (running the WSGI application) without having to become root.

* All files placed in the website directory should be either created there

  directly, or copied to the directory in order to make sure the ``SGID`` gets

  honored. **Do not move the files, the permissions will not be set correctly.**

* Within the website directory, Python virtual environment can be found within

* Within the website directory, nginx will expect to find the static files

  within the ``htdocs`` sub-directory (this can be symlink too). Locations/aliases

  can be configured for static file serving.

* Within the website directory, systemd service will expect to find the website

  code within the ``code`` sub-directory (this can be symlink too).

* nginx communicates with WSGI server over a dedicated Unix socket for each

  **comment** (string, mandatory)

    Comment describing the configuration option.

  **value** (string, mandatory)

    Configuration option.

**enforce_https** (boolean, optional, ``True``)

  Specify if HTTPS should be enforced for the website or not. If enforced,

  clients connecting via plaintext will be redirected to HTTPS.

**fqdn** (string, mandatory)

Here is an example configuration for setting-up a (base) WSGI website (for

running a bare Django project):

.. code-block:: yaml

    - role: wsgi_website

      fqdn: django.example.com

      static_locations:

        - /static

        - /media

      uid: 2004

      virtualenv_packages:

Before we start, here is a couple of useful pointers regarding the

``php_website`` role we'll be using for the PHP part:

* The role is designed to execute every application via dedicated user and

  group. The user/group name is automatically derived from the FQDN of website,

  for example ``web-tbg_example_com``.

* PHP applications are executed via FastCGI, using the ``php5-fpm`` package.

* Static content (non-PHP) is served directly by *Nginx*.

* Each web application gets distinct sub-directory under ``/var/www``, named

  after the FQDN. All sub-directories created under there are created with

  ``2750`` permissions, with ownership set to admin user, and group set to the

  application's group. In other words, all directories will have ``SGID`` bit

  set-up, allowing you to create files/directories that will have their group

  automatically set to the group of the parent directory.

      ---

      dependencies:

         # Ok, so this role helps us set-up Nginx virtual host for serving our

         # app.

         - role: php_website

           # Our virtual host will for PHP website will respond to this name.

           fqdn: tbg.example.com

           # Some additional packages are required in order to deploy and use TBG.

           packages:

              - php5-gd

              - php5-curl

      - name: Download the TBG archive

        get_url: url=https://github.com/thebuggenie/thebuggenie/archive/v{{ tbg_version }}.tar.gz

                 dest="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}.tar.gz"

                 sha256sum=0fd0a680ba281adc97d5d2c720e63b995225c99716a36eca6a198b8a5ebf8057

        become: yes

      - name: Download Composer

        get_url: url=https://getcomposer.org/download/1.0.0-alpha10/composer.phar

                 dest="/usr/local/bin/composer"

                 sha256sum=9f2c7d0364bc743bcde9cfe1fe84749e5ac38c46d47cf42966ce499135fd4628

                 owner=root group=root mode=755

      - name: Unpack TBG

        unarchive: src="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}.tar.gz"

                   dest="/var/www/tbg.example.com/" copy=no

                   creates="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}"

        become: yes

      - name: Create TBG cache directory

        file: path="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/cache" state=directory mode=2770

        become: yes

      - name: Set-up the necessary write permissions for TBG directories

        file: path="{{ item }}" mode=g+w

        with_items:

           - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/

           - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/public/

           - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/core/config/

      - name: Create symbolic link to TBG application

        file: src="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/public"

              path="/var/www/tbg.example.com/htdocs"

              state=link

        become: yes

      - name: Install TBG dependencies

        composer: command=install working_dir="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}"

        become: yes

      - name: Deploy database configuration file for TBG

        copy: src="b2db.yml" dest="/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/core/config/b2db.yml"

      - name: Deploy expect script for installing TBG

        copy: src="tbg_expect_install" dest="/var/www/tbg.example.com/tbg_expect_install" mode=750

        become: yes

      - name: Run TBG installer via expect script

        command: /var/www/tbg.example.com/tbg_expect_install

                 chdir=/var/www/tbg.example.com/thebuggenie-{{ tbg_version }} 

                 creates=/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/installed

        become: yes

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

   :file:`~/mysite/roles/tbg/files/b2db.yml`

   ::

``wsgi_website`` role, but we will reiterate and clarify them a bit just to be

on the safe side:

* The role is designed to execute every application via dedicated user and

  group. The user/group name is automatically derived from the FQDN of website,

  for example ``web-wiki_example_com``.

* WSGI applications are executed via *Gunicorn*. The WSGI server listens on a

  Unix socket, making the socket accessible by *Nginx*.

* Static content is served directly by *Nginx*.

* Each web application gets distinct sub-directory under ``/var/www``, named

  after the FQDN. All sub-directories created under there are created with

  ``2750`` permissions, with ownership set to admin user, and group set to the

  application's group. In other words, all directories will have ``SGID`` bit

  set-up, allowing you to create files/directories that will have their group

  automatically set to the group of the parent directory.

   ::

      ---

      dependencies:

         - role: wsgi_website

           fqdn: wiki.example.com

           # In many cases you need to have some development packages available

           # in order to build Python packages installed via pip

           packages:

              - build-essential

              - python-dev

   ::

      ---

      - name: Create Django project directory

        file: dest="/var/www/wiki.example.com/code" state=directory

              mode=2750

      - name: Start Django project for the Wiki website

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

                 chdir=/var/www/wiki.example.com

                 creates=/var/www/wiki.example.com/code/wiki_example_com

        become: yes

      - name: Deploy settings for wiki website

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

              mode=640 owner=admin group=web-wiki_example_com

        with_items:

           - settings.py

      - name: Deploy project database and deploy static files

        django_manage: command="{{ item }}"

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

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

        become: yes

        with_items:

           - syncdb

           - migrate

           - collectstatic

      - name: Deploy the superadmin creation script

        copy: src="create_superadmin.py" dest="/var/www/wiki.example.com/code/create_superadmin.py"

      - name: Create initial superuser

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

                 chdir=/var/www/wiki.example.com/code/

        become: yes

        register: wiki_superuser

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

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

   tasks. Let's create them as well.

enforce_https: True

index: index.php

packages: []

php_file_regex: \.php$

php_rewrite_urls: []

rewrites: []

https_tls_certificate: "{{ lookup('file', tls_certificate_dir + '/' + fqdn + '_https.pem') }}"

https_tls_key: "{{ lookup('file', tls_private_key_dir + '/' + fqdn + '_https.key') }}"

---

- name: Calculate username and home

  set_fact:

    user: "web-{{ fqdn | replace('.', '_') }}"

    home: "/var/www/{{ fqdn }}"

- name: Create PHP website group

  group: name="{{ user }}" gid="{{ uid | default(omit) }}" state=present

- name: Create home directory for the user (avoid populating with skeleton)

  file: path="{{ home }}" state=directory

        owner="{{ admin }}" group="{{ user }}" mode=2750

- name: Create PHP website user

  user: name="{{ user }}" uid="{{ uid | default(omit) }}" group="{{ user }}"

---

- set_fact:

    user: "web-{{ fqdn | replace('.', '_') }}"

    home: "/var/www/{{ fqdn }}"

- name: Create WSGI website group

  group: name="{{ user }}" gid="{{ uid | default(omit) }}" state=present

- name: Create home directory for the user (avoid populating with skeleton)

  file: path="{{ home }}" state=directory

        owner="{{ admin }}" group="{{ user }}" mode=2750

- name: Create WSGI website user

  user: name="{{ user }}" uid="{{ uid | default(omit) }}" group="{{ user }}"

  command: /usr/bin/virtualenv --prompt "({{ fqdn }})" "{{ home }}/virtualenv" creates="{{ home }}/virtualenv/bin/activate"

- name: Configure project directory for the Python virtual environment

  template: src="venv_project.j2" dest="{{ home }}/virtualenv/.project"

            owner="{{ admin }}" group="{{ user }}" mode="640"

- name: Deploy virtualenv wrapper

  template: src="venv_exec.j2" dest="{{ home }}/virtualenv/bin/exec"

            owner="{{ admin }}" group="{{ user }}" mode="750"

- name: Install futures package for use with Gunicorn thread workers

  become_user: "{{ admin }}"

  pip: name=futures version="{{ futures_version }}" state=present virtualenv="{{ home }}/virtualenv"

- name: Install Gunicorn in Python virtual environment

  become_user: "{{ admin }}"

---

dependencies:

  - role: php_website

    fqdn: phpinfo.{{ testsite_domain }}

    php_rewrite_urls:

      - ^(.*) /index.php

    uid: 2000

    enforce_https: False

    https_tls_key: "{{ lookup('file', inventory_dir + '/tls/phpinfo.' + testsite_domain + '_https.key') }}"

    https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/phpinfo.' + testsite_domain + '_https.pem') }}"

  - role: database

    db_name: phpinfo_{{ testsite_domain_underscores }}

---

dependencies:

  - role: wsgi_website

    admin: admin

    fqdn: wsgi.{{ testsite_domain }}

    uid: 2001

    wsgi_application: wsgi:application

    static_locations:

      - /static/

    https_tls_key: "{{ lookup('file', inventory_dir + '/tls/wsgi.' + testsite_domain + '_https.key') }}"

    https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/wsgi.' + testsite_domain + '_https.pem') }}"