| 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 |
| 254710 | 12 | was developed under Apple's macOS platform (Snow Leopard, on a 32-bit |
| b9065f | 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 | |
| 6b6d0e | 35 | #. Create a :app:`Pyramid` application using our :term:`cookiecutter`. See |
| SM | 36 | :ref:`project_narr` for more in-depth information about creating a new |
| 37 | project. | |
| 9c5a10 | 38 | |
| 7af933 | 39 | .. code-block:: bash |
| 9c5a10 | 40 | |
| 733452 | 41 | cd ~ |
| 0080e9 | 42 | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| 2cd381 | 43 | |
| SP | 44 | If prompted for the first item, accept the default ``yes`` by hitting return. |
| 45 | ||
| 46 | .. code-block:: text | |
| 47 | ||
| 28e688 | 48 | You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. |
| 2cd381 | 49 | Is it okay to delete and re-clone it? [yes]: yes |
| SP | 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 |
| 6b6d0e | 56 | Choose from 1, 2, 3 [1]: 1 |
| SM | 57 | Select backend: |
| 58 | 1 - none | |
| 59 | 2 - sqlalchemy | |
| 60 | 3 - zodb | |
| 6204d8 | 61 | Choose from 1, 2, 3 [1]: 1 |
| 7af933 | 62 | |
| MM | 63 | #. Create a :term:`virtual environment` which we'll use to install our |
| 64 | application. It is important to use the same base Python interpreter | |
| 65 | that was used to build ``mod_wsgi``. For example, if ``mod_wsgi`` was | |
| 66 | built against the system Python 3.x, then your project should use a | |
| 67 | virtual environment created from that same system Python 3.x. | |
| 68 | ||
| 69 | .. code-block:: bash | |
| 70 | ||
| 733452 | 71 | cd myproject |
| SP | 72 | python3 -m venv env |
| 9c5a10 | 73 | |
| 7af933 | 74 | #. Install your :app:`Pyramid` application and its dependencies. |
| 9c5a10 | 75 | |
| 7af933 | 76 | .. code-block:: bash |
| 9c5a10 | 77 | |
| 733452 | 78 | env/bin/pip install -e . |
| ac4d2c | 79 | |
| 7af933 | 80 | #. Within the project directory (``~/myproject``), create a script |
| MM | 81 | named ``pyramid.wsgi``. Give it these contents: |
| 9c5a10 | 82 | |
| 125e97 | 83 | .. code-block:: python |
| 9c5a10 | 84 | |
| 733452 | 85 | from pyramid.paster import get_app, setup_logging |
| SP | 86 | ini_path = '/Users/chrism/myproject/production.ini' |
| 87 | setup_logging(ini_path) | |
| 88 | application = get_app(ini_path, 'main') | |
| 9c5a10 | 89 | |
| 7af933 | 90 | The first argument to :func:`pyramid.paster.get_app` is the project |
| MM | 91 | configuration file name. It's best to use the ``production.ini`` file |
| 92 | provided by your cookiecutter, as it contains settings appropriate for | |
| 93 | production. The second is the name of the section within the ``.ini`` | |
| 94 | file that should be loaded by ``mod_wsgi``. The assignment to the name | |
| 43ab04 | 95 | ``application`` is important: mod_wsgi requires finding such an |
| CM | 96 | assignment when it opens the file. |
| 9c5a10 | 97 | |
| 7af933 | 98 | The call to :func:`pyramid.paster.setup_logging` initializes the standard |
| MM | 99 | library's `logging` module to allow logging within your application. |
| 14f9fe | 100 | See :ref:`logging_config`. |
| MM | 101 | |
| b9065f | 102 | There is no need to make the ``pyramid.wsgi`` script executable. |
| b26206 | 103 | However, you'll need to make sure that *two* users have access to change |
| 7af933 | 104 | into the ``~/myproject`` directory: your current user (mine is |
| b26206 | 105 | ``chrism`` and the user that Apache will run as often named ``apache`` or |
| CM | 106 | ``httpd``). Make sure both of these users can "cd" into that directory. |
| 9c5a10 | 107 | |
| CM | 108 | #. Edit your Apache configuration and add some stuff. I happened to |
| 109 | create a file named ``/etc/apache2/other/modwsgi.conf`` on my own | |
| 110 | system while installing Apache, so this stuff went in there. | |
| 111 | ||
| 913e6f | 112 | .. code-block:: apache |
| 9c5a10 | 113 | |
| 733452 | 114 | # Use only 1 Python sub-interpreter. Multiple sub-interpreters |
| SP | 115 | # play badly with C extensions. See |
| 116 | # http://stackoverflow.com/a/10558360/209039 | |
| 117 | WSGIApplicationGroup %{GLOBAL} | |
| 118 | WSGIPassAuthorization On | |
| 119 | WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \ | |
| 7af933 | 120 | python-path=/Users/chrism/myproject/env/lib/python3.5/site-packages |
| 733452 | 121 | WSGIScriptAlias /myapp /Users/chrism/myproject/pyramid.wsgi |
| 9c5a10 | 122 | |
| 733452 | 123 | <Directory /Users/chrism/myproject> |
| e6261f | 124 | WSGIProcessGroup pyramid |
| 7af933 | 125 | Require all granted |
| 733452 | 126 | </Directory> |
| 6b6d0e | 127 | |
| 9c5a10 | 128 | #. Restart Apache |
| CM | 129 | |
| 7af933 | 130 | .. code-block:: bash |
| 9c5a10 | 131 | |
| 733452 | 132 | sudo /usr/sbin/apachectl restart |
| 9c5a10 | 133 | |
| CM | 134 | #. Visit ``http://localhost/myapp`` in a browser. You should see the |
| 135 | sample application rendered in your browser. | |
| 136 | ||
| 1cb30e | 137 | :term:`mod_wsgi` has many knobs and a great variety of deployment modes. This |
| SP | 138 | is just one representation of how you might use it to serve up a :app:`Pyramid` |
| 139 | application. See the `mod_wsgi configuration documentation | |
| ce8894 | 140 | <https://modwsgi.readthedocs.io/en/develop/configuration.html>`_ |
| 1cb30e | 141 | for more in-depth configuration information. |
