| commit | author | age | ||
| 9c5a10 | 1 | .. _modwsgi_tutorial: |
| CM | 2 | |
| fd5ae9 | 3 | Running a :app:`Pyramid` Application under ``mod_wsgi`` |
| 3c6d7e | 4 | ======================================================= |
| 9c5a10 | 5 | |
| CM | 6 | :term:`mod_wsgi` is an Apache module developed by Graham Dumpleton. |
| 7 | It allows :term:`WSGI` programs to be served using the Apache web | |
| 8 | server. | |
| 9 | ||
| b9065f | 10 | This guide will outline broad steps that can be used to get a :app:`Pyramid` |
| CM | 11 | application running under Apache via ``mod_wsgi``. This particular tutorial |
| 12 | was developed under Apple's Mac OS X platform (Snow Leopard, on a 32-bit | |
| 13 | Mac), but the instructions should be largely the same for all systems, delta | |
| 8a939c | 14 | specific path information for commands and files. |
| 9c5a10 | 15 | |
| d6a7d8 | 16 | .. note:: Unfortunately these instructions almost certainly won't work for |
| CM | 17 | deploying a :app:`Pyramid` application on a Windows system using |
| 18 | ``mod_wsgi``. If you have experience with :app:`Pyramid` and ``mod_wsgi`` | |
| 19 | on Windows systems, please help us document this experience by submitting | |
| 20 | documentation to the `Pylons-devel maillist | |
| 1cb30e | 21 | <https://groups.google.com/forum/#!forum/pylons-devel>`_. |
| 9c5a10 | 22 | |
| CM | 23 | #. The tutorial assumes you have Apache already installed on your |
| 24 | system. If you do not, install Apache 2.X for your platform in | |
| 25 | whatever manner makes sense. | |
| 26 | ||
| d67566 | 27 | #. It is also assumed that you have satisfied the |
| SP | 28 | :ref:`requirements-for-installing-packages`. |
| 29 | ||
| 9c5a10 | 30 | #. Once you have Apache installed, install ``mod_wsgi``. Use the |
| CM | 31 | (excellent) `installation instructions |
| 1cb30e | 32 | <https://code.google.com/archive/p/modwsgi/wikis/InstallationInstructions.wiki>`_ |
| 9c5a10 | 33 | for your platform into your system's Apache installation. |
| CM | 34 | |
| 7af933 | 35 | #. Create a :app:`Pyramid` application. For this tutorial we'll use the |
| MM | 36 | ``starter`` :term:`cookiecutter`. See :ref:`project_narr` for more |
| 37 | in-depth information about creating a new project. | |
| 9c5a10 | 38 | |
| 7af933 | 39 | .. code-block:: bash |
| 9c5a10 | 40 | |
| CM | 41 | $ cd ~ |
| 1aa283 | 42 | $ cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.9-branch |
| 2cd381 | 43 | |
| SP | 44 | If prompted for the first item, accept the default ``yes`` by hitting return. |
| 45 | ||
| 46 | .. code-block:: text | |
| 47 | ||
| 48 | You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. | |
| 49 | Is it okay to delete and re-clone it? [yes]: yes | |
| 50 | project_name [Pyramid Scaffold]: myproject | |
| 6ff6fa | 51 | repo_name [myproject]: myproject |
| 2cd381 | 52 | Select template_language: |
| SP | 53 | 1 - jinja2 |
| 54 | 2 - chameleon | |
| 6204d8 | 55 | 3 - mako |
| SP | 56 | Choose from 1, 2, 3 [1]: 1 |
| 7af933 | 57 | |
| MM | 58 | #. Create a :term:`virtual environment` which we'll use to install our |
| 59 | application. It is important to use the same base Python interpreter | |
| 60 | that was used to build ``mod_wsgi``. For example, if ``mod_wsgi`` was | |
| 61 | built against the system Python 3.x, then your project should use a | |
| 62 | virtual environment created from that same system Python 3.x. | |
| 63 | ||
| 64 | .. code-block:: bash | |
| 65 | ||
| 66 | $ cd myproject | |
| d67566 | 67 | $ python3 -m venv env |
| 9c5a10 | 68 | |
| 7af933 | 69 | #. Install your :app:`Pyramid` application and its dependencies. |
| 9c5a10 | 70 | |
| 7af933 | 71 | .. code-block:: bash |
| 9c5a10 | 72 | |
| 7af933 | 73 | $ env/bin/pip install -e . |
| ac4d2c | 74 | |
| 7af933 | 75 | #. Within the project directory (``~/myproject``), create a script |
| MM | 76 | named ``pyramid.wsgi``. Give it these contents: |
| 9c5a10 | 77 | |
| 125e97 | 78 | .. code-block:: python |
| 9c5a10 | 79 | |
| 14f9fe | 80 | from pyramid.paster import get_app, setup_logging |
| 7af933 | 81 | ini_path = '/Users/chrism/myproject/production.ini' |
| 14f9fe | 82 | setup_logging(ini_path) |
| MM | 83 | application = get_app(ini_path, 'main') |
| 9c5a10 | 84 | |
| 7af933 | 85 | The first argument to :func:`pyramid.paster.get_app` is the project |
| MM | 86 | configuration file name. It's best to use the ``production.ini`` file |
| 87 | provided by your cookiecutter, as it contains settings appropriate for | |
| 88 | production. The second is the name of the section within the ``.ini`` | |
| 89 | file that should be loaded by ``mod_wsgi``. The assignment to the name | |
| 43ab04 | 90 | ``application`` is important: mod_wsgi requires finding such an |
| CM | 91 | assignment when it opens the file. |
| 9c5a10 | 92 | |
| 7af933 | 93 | The call to :func:`pyramid.paster.setup_logging` initializes the standard |
| MM | 94 | library's `logging` module to allow logging within your application. |
| 14f9fe | 95 | See :ref:`logging_config`. |
| MM | 96 | |
| b9065f | 97 | There is no need to make the ``pyramid.wsgi`` script executable. |
| b26206 | 98 | However, you'll need to make sure that *two* users have access to change |
| 7af933 | 99 | into the ``~/myproject`` directory: your current user (mine is |
| b26206 | 100 | ``chrism`` and the user that Apache will run as often named ``apache`` or |
| CM | 101 | ``httpd``). Make sure both of these users can "cd" into that directory. |
| 9c5a10 | 102 | |
| CM | 103 | #. Edit your Apache configuration and add some stuff. I happened to |
| 104 | create a file named ``/etc/apache2/other/modwsgi.conf`` on my own | |
| 105 | system while installing Apache, so this stuff went in there. | |
| 106 | ||
| 913e6f | 107 | .. code-block:: apache |
| 9c5a10 | 108 | |
| CM | 109 | # Use only 1 Python sub-interpreter. Multiple sub-interpreters |
| 49ebfe | 110 | # play badly with C extensions. See |
| CM | 111 | # http://stackoverflow.com/a/10558360/209039 |
| 913e6f | 112 | WSGIApplicationGroup %{GLOBAL} |
| 9c5a10 | 113 | WSGIPassAuthorization On |
| 02fe94 | 114 | WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \ |
| 7af933 | 115 | python-path=/Users/chrism/myproject/env/lib/python3.5/site-packages |
| MM | 116 | WSGIScriptAlias /myapp /Users/chrism/myproject/pyramid.wsgi |
| 9c5a10 | 117 | |
| 7af933 | 118 | <Directory /Users/chrism/myproject> |
| e6261f | 119 | WSGIProcessGroup pyramid |
| 7af933 | 120 | Require all granted |
| 9c5a10 | 121 | </Directory> |
| CM | 122 | |
| 123 | #. Restart Apache | |
| 124 | ||
| 7af933 | 125 | .. code-block:: bash |
| 9c5a10 | 126 | |
| 125e97 | 127 | $ sudo /usr/sbin/apachectl restart |
| 9c5a10 | 128 | |
| CM | 129 | #. Visit ``http://localhost/myapp`` in a browser. You should see the |
| 130 | sample application rendered in your browser. | |
| 131 | ||
| 1cb30e | 132 | :term:`mod_wsgi` has many knobs and a great variety of deployment modes. This |
| SP | 133 | is just one representation of how you might use it to serve up a :app:`Pyramid` |
| 134 | application. See the `mod_wsgi configuration documentation | |
| ce8894 | 135 | <https://modwsgi.readthedocs.io/en/develop/configuration.html>`_ |
| 1cb30e | 136 | for more in-depth configuration information. |
