diff --git a/docs/rolereference.rst b/docs/rolereference.rst index 3ec43a8204b4a5a82d57cdba71bc445d8a26fbd5..86f3b8ee7e72204c9efe9043b4a26e741f34e513 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -896,7 +896,7 @@ Here is an example configuration for setting-up web server: PHP Website --------- +----------- The ``php_website`` role can be used for setting-up a website powered by PHP on destination machine. @@ -1013,3 +1013,133 @@ Here is an example configuration for setting-up a (base) PHP website (for runnin - php5-json - php5-mysql - php5-curl + + +WSGI Website +------------ + +The ``wsgi_website`` role can be used for setting-up a website powered by Python +on destination machine. The website needs to use the WSGI specification for +making the Python web application(s) available. + +This role is normally not supposed to be used directly, but should instead serve +as the basis for writing website-specific roles. Therefore the role is written +in quite generic way, allowing the integrator to write his/her own logic for +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). +* Sets-up a dedicated Python virtual environment for website. +* Install Gunicorn in Python virtual environment. +* Installs additional packages required for running the role in Python virtual + environment (as configured). +* Configures systemd to run the website code (using Gunicorn) +* Configures nginx to serve the website (static files served directly, requests + passed on to Gunicorn). + +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 + the ``virtualenv`` sub-directory. The virtual environment is also symlinked to + website admin's ``~/.virtualenvs/`` directory for easier access (and + auto-completion with virtualenvwrapper). +* 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. + + +Parameters +~~~~~~~~~~ + +**admin** (string, mandatory) + Name of the operating system user in charge of maintaining the website. This + user is capable of making modifications to website configuration anda data + stored within the website directory. + +**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). + +**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. + +**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, mandatory) + UID/GID (they are set-up to be the same) of the dedicated website + user/group. + +**use_paste** (boolean, optional) + 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 PHP + appliction. This is usually going to be different PHP extensions. + +**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. + + +Examples +~~~~~~~~ + +Here is an example configuration for setting-up a (base) WSGI website (for +running a bare Django project): + +.. code-block:: yaml + + --- + + - role: wsgi_website + admin: admin + fqdn: django.example.com + static_locations: + - /static + - /media + uid: 2004 + virtualenv_packages: + - django + wsgi_application: django_example_com.wsgi:application