Merge pull request #3390 from mmerickel/whatsnew-1.10

Michael Merickel

2018-10-16 8eed333343e4e9e7f11f3aee67299030d6bf2783

 docs/tutorials/modwsgi/index.rst

@@ -1,96 +1,109 @@
.. _modwsgi_tutorial:

Running a :app:`Pyramid` Application under ``mod_wsgi``
==========================================================
=======================================================

:term:`mod_wsgi` is an Apache module developed by Graham Dumpleton.
It allows :term:`WSGI` programs to be served using the Apache web
server.

This guide will outline broad steps that can be used to get a
:app:`Pyramid` application running under Apache via ``mod_wsgi``.
This particular tutorial was developed under Apple's Mac OS X platform
(Snow Leopard, on a 32-bit Mac), but the instructions should be
largely the same for all systems, delta specific path information for
commands and files.
This guide will outline broad steps that can be used to get a :app:`Pyramid`
application running under Apache via ``mod_wsgi``.  This particular tutorial
was developed under Apple's macOS platform (Snow Leopard, on a 32-bit
Mac), but the instructions should be largely the same for all systems, delta
specific path information for commands and files.

.. note:: Unfortunately these instructions almost certainly won't work for
   deploying a :app:`Pyramid` application on a Windows system using
   ``mod_wsgi``.  If you have experience with :app:`Pyramid` and ``mod_wsgi``
   on Windows systems, please help us document this experience by submitting
   documentation to the `Pylons-devel maillist
   <http://groups.google.com/group/pylons-devel>`_.
   <https://groups.google.com/forum/#!forum/pylons-devel>`_.

#.  The tutorial assumes you have Apache already installed on your
    system.  If you do not, install Apache 2.X for your platform in
    whatever manner makes sense.

#.  It is also assumed that you have satisfied the
    :ref:`requirements-for-installing-packages`.

#.  Once you have Apache installed, install ``mod_wsgi``.  Use the
    (excellent) `installation instructions
    <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
    <https://code.google.com/archive/p/modwsgi/wikis/InstallationInstructions.wiki>`_
    for your platform into your system's Apache installation.

#.  Install :term:`virtualenv` into the Python which mod_wsgi will
    run using the ``easy_install`` program.
#.  Create a :app:`Pyramid` application using our :term:`cookiecutter`. See
    :ref:`project_narr` for more in-depth information about creating a new
    project.

    .. code-block:: bash

        cd ~
        cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch

    If prompted for the first item, accept the default ``yes`` by hitting return.

    .. code-block:: text

       $ sudo /usr/bin/easy_install-2.6 virtualenv
        You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
        Is it okay to delete and re-clone it? [yes]: yes
        project_name [Pyramid Scaffold]: myproject
        repo_name [myproject]: myproject
        Select template_language:
        1 - jinja2
        2 - chameleon
        3 - mako
        Choose from 1, 2, 3 [1]: 1
        Select backend:
        1 - none
        2 - sqlalchemy
        3 - zodb
        Choose from 1, 2, 3 [1]: 1

    This command may need to be performed as the root user.
#.  Create a :term:`virtual environment` which we'll use to install our
    application. It is important to use the same base Python interpreter
    that was used to build ``mod_wsgi``. For example, if ``mod_wsgi`` was
    built against the system Python 3.x, then your project should use a
    virtual environment created from that same system Python 3.x.

#.  Create a :term:`virtualenv` which we'll use to install our
    application.
    .. code-block:: bash

    .. code-block:: text
        cd myproject
        python3 -m venv env

       $ cd ~
       $ mkdir modwsgi
       $ cd modwsgi
       $ /usr/local/bin/virtualenv --no-site-packages env
#.  Install your :app:`Pyramid` application and its dependencies.

#.  Install :app:`Pyramid` into the newly created virtualenv:
    .. code-block:: bash

    .. code-block:: text
        env/bin/pip install -e .

       $ cd ~/modwsgi/env
       $ bin/easy_install pyramid
    
#.  Create and install your :app:`Pyramid` application.  For the purposes of
    this tutorial, we'll just be using the ``pyramid_starter`` application as
    a baseline application.  Substitute your existing :app:`Pyramid`
    application as necessary if you already have one.

    .. code-block:: text

       $ cd ~/modwsgi/env
       $ bin/pcreate -s starter myapp
       $ cd myapp
       $ ../bin/python setup.py install

#.  Within the virtualenv directory (``~/modwsgi/env``), create a
    script named ``pyramid.wsgi``.  Give it these contents:
#.  Within the project directory (``~/myproject``), create a script
    named ``pyramid.wsgi``.  Give it these contents:

    .. code-block:: python

       from pyramid.paster import get_app
       application = get_app(
         '/Users/chrism/modwsgi/env/myapp/production.ini', 'main')
        from pyramid.paster import get_app, setup_logging
        ini_path = '/Users/chrism/myproject/production.ini'
        setup_logging(ini_path)
        application = get_app(ini_path, 'main')

    The first argument to ``get_app`` is the project configuration file
    name.  It's best to use the ``production.ini`` file provided by your
    scaffold, as it contains settings appropriate for
    production.  The second is the name of the section within the .ini file
    that should be loaded by ``mod_wsgi``.  The assignment to the name
    The first argument to :func:`pyramid.paster.get_app` is the project
    configuration file name.  It's best to use the ``production.ini`` file
    provided by your cookiecutter, as it contains settings appropriate for
    production.  The second is the name of the section within the ``.ini``
    file that should be loaded by ``mod_wsgi``.  The assignment to the name
    ``application`` is important: mod_wsgi requires finding such an
    assignment when it opens the file.

#.  Make the ``pyramid.wsgi`` script executable.
    The call to :func:`pyramid.paster.setup_logging` initializes the standard
    library's `logging` module to allow logging within your application.
    See :ref:`logging_config`.

    .. code-block:: text

       $ cd ~/modwsgi/env
       $ chmod 755 pyramid.wsgi
    There is no need to make the ``pyramid.wsgi`` script executable.
    However, you'll need to make sure that *two* users have access to change
    into the ``~/myproject`` directory: your current user (mine is
    ``chrism`` and the user that Apache will run as often named ``apache`` or
    ``httpd``).  Make sure both of these users can "cd" into that directory.

#.  Edit your Apache configuration and add some stuff.  I happened to
    create a file named ``/etc/apache2/other/modwsgi.conf`` on my own
@@ -98,33 +111,31 @@

    .. code-block:: apache

       # Use only 1 Python sub-interpreter.  Multiple sub-interpreters
       # play badly with C extensions.
       WSGIApplicationGroup %{GLOBAL}
       WSGIPassAuthorization On
       WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \
          python-path=/Users/chrism/modwsgi/env/lib/python2.6/site-packages
       WSGIScriptAlias /myapp /Users/chrism/modwsgi/env/pyramid.wsgi
        # Use only 1 Python sub-interpreter.  Multiple sub-interpreters
        # play badly with C extensions.  See
        # http://stackoverflow.com/a/10558360/209039
        WSGIApplicationGroup %{GLOBAL}
        WSGIPassAuthorization On
        WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \
          python-path=/Users/chrism/myproject/env/lib/python3.5/site-packages
        WSGIScriptAlias /myapp /Users/chrism/myproject/pyramid.wsgi

       <Directory /Users/chrism/modwsgi/env>
        <Directory /Users/chrism/myproject>
         WSGIProcessGroup pyramid
         Order allow,deny
         Allow from all
       </Directory>
 
         Require all granted
        </Directory>

#.  Restart Apache

    .. code-block:: text
    .. code-block:: bash

       $ sudo /usr/sbin/apachectl restart
        sudo /usr/sbin/apachectl restart

#.  Visit ``http://localhost/myapp`` in a browser.  You should see the
    sample application rendered in your browser.

:term:`mod_wsgi` has many knobs and a great variety of deployment
modes.  This is just one representation of how you might use it to
serve up a :app:`Pyramid` application.  See the `mod_wsgi
configuration documentation
<http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines>`_ for
more in-depth configuration information.

:term:`mod_wsgi` has many knobs and a great variety of deployment modes. This
is just one representation of how you might use it to serve up a :app:`Pyramid`
application.  See the `mod_wsgi configuration documentation
<https://modwsgi.readthedocs.io/en/develop/configuration.html>`_
for more in-depth configuration information.