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

  of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal

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

  ``admin-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

  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

  the ``virtualenv`` sub-directory. Switching to administrator user via login

  shell will automatically activate the virtual environment.

* 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

  website.

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

* **web_server**

Parameters

~~~~~~~~~~

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

  List providing additional Nginx configuration options to include. This can be

  useful for specifying things like error pages. Options are applied inside of a

  **server** context of Nginx configuration file.

  Each item is a dictionary with the following options describing the extra

  configuration option:

  **comment** (string, mandatory)

    Comment describing the configuration option.

  **value** (string, mandatory)

    Configuration option.

**admin_uid** (integer, optional, ``whatever OS picks``)

  UID of the dedicated website administrator user. The user will be member of

  website group.

**environment_indicator** (dictionary, optional, ``null``)

  Specify configuration for including environment indicator on all HTML

  pages. Indicator is a simple strip at bottom of a page with custom background

  colour, text colour, and text.

  Specifying environment indicator is useful for avoiding mistakes when testing

  by having better visibility what environment you are in

  (production/staging/test).

  The following keys need to be specified:

  **background_colour** (string, mandatory)

    Background colour to use for the strip at bottom. This should be value

    compatible with CSS ``background-color`` attribute.

  **text_colour** (string, mandatory

    Text colour to use for the strip at bottom. This should be value compatible

    with CSS ``color`` attribute.

  **text** (string, mandatory)

    Text to show in show in the strip at bottom.

**environment_variables** (dict, optional, ``{}``)

  Specify additional environment variables that should be set for running the

  service. Environment variables will be set in both the systemd service and for

  the application's administrator user (when logged in as one).

**fqdn** (string, mandatory)

  Fully-qualified domain name where the website is reachable. This value is used

  for calculating the user/group name for dedicated website user, as well as

  home directory of the website user (where data/code should be stored at).

**https_tls_certificate** (string, mandatory)

  X.509 certificate used for TLS for HTTPS service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``.

**https_tls_key** (string, mandatory)

  Private key used for TLS for HTTPS service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``.

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

  A list of additional packages to install for this particular WSGI

  website. This is usually going to be development libraries for building Python

  packages.

**proxy_headers** (dictionary, optional, ``{}``)

  Additional headers to set when proxying request to Gunicorn. Keys are header

  names, values are header values. Both should be compatible with Nginx

  ``proxy_set_header``. If you need to provide an empty value, use quotes (don't

  forget to surround them by another set of quotes for YAML syntax, for example

  ``"\"\""`` or ``'""'``).

**python_version** (string, optional, ``2``)

  Python version to use when setting-up the Python virtual environment.

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

  A list of rewrite rules that are applied to incoming requests. Each element of

  the list should be a string value compatible with the format of ``nginx``

  option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well

  as trailing semi-colon (``;``).

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

  List of locations that should be treated as static-only, and not processed by

  the WSGI application at all. This is normally used for designating serving of

  static/media files by Nginx (for example, in case of Django projects for

  ``/static/`` and ``/media/``).

**uid** (integer, optional, ``whatever OS picks``)

  UID/GID (they are set-up to be the same) of the dedicated website

  user/group.

**use_paste** (boolean, optional, ``False``)

  Tell Gunicorn to assume that the passed-in ``wsgi_application`` value is a

  filename of a Python Paste ``ini`` file instead of WSGI application.

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

  A list of additional packages to install for this particular WSGI appliction

  in its virtual environment using ``pip``.

**website_mail_recipients** (string, optional, ``root``)

  Space-separated list of e-mails or local users to which the mails, sent to

  either the website admin or website user, should be forwarded to. Forwarding

  is configured via ``~/.forward`` configuration file.

**wsgi_application** (string, mandatory)

  WSGI application that should be started by Gunicorn. The format should be

  conformant to what the ``gunicorn`` command-line tool accepts. If the

  ``use_paste`` option is enabled, the value should be equal to filename of the

  Python Paste ini file, located in the ``code`` sub-directory. It should be

  noted that in either case the value should be specsified relative to the

  ``code`` sub-directory. I.e. don't use full paths.

**wsgi_requirements** (list, optional, ``[ futures==3.3.0, gunicorn==19.10.0 ]``)

  Complete list of pip requirements used for deploying Gunicorn. If

  specified, this list will be used to create requirements file and

  install Gunicorn and its dependencies from that one. This allows to

  have pinned packages for both Gunicorn, futures, and their

  dependencies. The ``futures`` package is required by Gunicorn when

  using Python 2.7.

  It should be noted that this installation method is meant primarily in case of

  roles that want to take advantage of upgrade checks for pip requirements

  files, and that employ `pip-tools <https://github.com/jazzband/pip-tools>`_.

  In addition to change of installation method, when this parameter is

  specified the role will deploy necessary files for running the pip

  requirements upgrade check (see the ``common`` role for

  description). For this a directory is created under

  ``/etc/pip_check_requirements_upgrades/FQDN`` for Python 2 or

  ``/etc/pip_check_requirements_upgrades-py3/FQDN`` for Python 3. The same

  directory should be used by dependant roles to deploy their own

  ``.in`` and ``.txt`` files. Make sure the file ownership is set to

  ``root:pipreqcheck``.

  Should you need to utilise the requirements file in some manner (other than

  checking for its upgrades), it will be also stored (and made accessible to

  application user/admin)) in application's home directory under the name

  ``.wsgi_requirements.txt``.

  To create complete requirements list, it is recommended to use `pip-tools

  <https://github.com/jazzband/pip-tools>`_ (the ``pip-compile`` utility) with

  ``gunicorn`` and ``futures`` in the ``.in.`` file.

**wsgi_requirements_in** (list, optional, ``[ futures, gunicorn ]``)

  List of top level packages to use when performing the pip

  requirements upgrade checks for the Gunicorn requirements (listed

  via ``wsgi_requirements`` parameter). For Python 3-based websites,

  it should be sufficient to list only ``gunicorn`` (``futures`` is

  required for Python 2).

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

Examples

~~~~~~~~

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

running a bare Django project):

.. code-block:: yaml

    # Sample for a Django installation.

    - role: wsgi_website

      fqdn: django.example.com

      static_locations:

        - /static

        - /media

      uid: 2004

      virtualenv_packages:

        - django

      wsgi_application: django_example_com.wsgi:application

      environment_variables:

        DJANGO_SETTINGS_MODULE: "django_example_com.settings.production"

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

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

      additional_nginx_config:

        - comment: Use custom page for forbidden files.

          value: error_page 403 /static/403.html;

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

          value: error_page 404 /static/404.html;

      website_mail_recipients: "root john.doe@example.com"

      environment_indicator:

        background_colour: "green"

        text_colour: "black"

        text: "TEST ENVIRONMENT"

      proxy_headers:

        Accept-Encoding: '""'

    # Use wsgi_requirements to deploy Gunicorn.

    - role: wsgi_website

      fqdn: wsgi.example.com

      wsgi_application: wsgi:main

      wsgi_requirements:

        - gunicorn==19.7.1

	- futures==3.1.1

Database Server

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

The ``database_server`` role can be used for setting-up a MariaDB database

server on destination machine.

The role implements the following:

* Installs MariaDB server and client.

* Configures MariaDB server and client to use *UTF-8* encoding by default.

* Sets-up the database root user for passwordless login via UNIX

  socket authentication.

* Drops the ``debian-sys-maint`` database user (which was used in

  Debian Jessie and earlier for maintenance tasks) if it is present,

  and updates the Debian system maintenance configuration file to use

  the root account over unix socket authentication.

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

Parameters

~~~~~~~~~~

This role has no parameters.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

Examples

~~~~~~~~

This role has no parameters which can be configured configure.

Database

--------

The ``database`` role can be used for creating a MariaDB database and

accompanying user on destination machine.

The role implements the following:

* Creates MariaDB database.

* Creates a dedicated user capable of performing any operation on the created

  database. Username is set to be same as the name of database.

* Sets-up pre-backup task that creates database dump in location

  ``/srv/backup/mariadb/{{ db_name }}.sql``.

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **database_server**

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/srv/backup/maraidb/{{ db_name }}.sql**

  Dump of the database. Database dump is created every day at 01:45 in the

  morning.

Parameters

~~~~~~~~~~

**db_name** (string, mandatory)

  Name of the database that should be created.

**db_password** (string, mandatory)

  Password for the database user.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

Examples

~~~~~~~~

Here is an example configuration for creating a single database (for some

website):

.. code-block:: yaml

  - role: database

    db_name: phpinfo_example_com

    db_password: phpinfo_example_com

Backup Server

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

The ``backup_server`` role can be used for setting-up a server to act as backup

storage for the backup clients. Storage is made available to the clients

exclusively via SFTP on a dedicated port and dedicated OpenSSH server

instance. This instance is specifically configured and tailored for this

purpose.

The role is primarily aimed for use with `Duplicity

<http://duplicity.nongnu.org/>`_, but should be also usable for generic SFTP

uploads.

The role implements the following:

* Installs backup software (Duplicity, Duply).

* Creates a dedicated directory structure for backups with the following structure:

  * ``/srv/backups/`` - main directory under which all the backups reside.

  * ``/srv/backups/SERVER_NAME/`` - home directory for the backup user, name

    after the server. Backup users are confined to their respective home

    directory via chroot. Backup users can't write to their own home directory,

    though.

  * ``/srv/backups/SERVER_NAME/duplicity/`` - directory where the Duplicity

    backups are stored at. This directory is writable by the respective backup

    user.

  * ``SERVER_NAME/.ssh/`` - directory where authorized keys are stored. Backup

    user is not allowed to make modifications to this directory and files

    contained within (i.e. backup users can't add more keys to the

    ``authorized_keys`` file).

* Creates dedicated operating system users for backup clients. These users will

  be made members of the ``backup`` group as well (as an additional group).

* Sets-up ``authorized_keys`` for the backup clients.

* Makes sure the backup users can't log-in via regular OpenSSH server instance.

---

allow_duplicates: true

dependencies:

  - common

  - web_server

galaxy_info:

  author: Branko Majic

  description: Sets-up a website powered by WSGI application

  license: BSD

  min_ansible_version: 2.9

  platforms:

    - name: Debian

      versions:

        - 10

---

dependency: {}

driver:

  name: vagrant

  provider:

    name: virtualbox

lint:

  name: yamllint

  options:

    config-file: ../../.yamllint.yml

platforms:

  - name: wsgi-website-buster64

    groups:

      - wsgi-website

      - parameters-mandatory

      - parameters-optional

      - buster

    box: debian/contrib-buster64

    memory: 512

    cpus: 1

provisioner:

  name: ansible

  playbooks:

    cleanup: cleanup.yml

  config_options:

    defaults:

      force_valid_group_names: "ignore"

      interpreter_python: "/usr/bin/python3"

    ssh_connection:

      pipelining: "True"

  lint:

    name: ansible-lint

scenario:

  name: default

verifier:

  name: testinfra

  lint:

    name: flake8