diff options
| -rw-r--r-- | README.rst | 226 | ||||
| -rw-r--r-- | setup.py | 9 |
2 files changed, 160 insertions, 75 deletions
@@ -9,40 +9,59 @@ The mod_wsgi package provides an Apache module that implements a WSGI compliant interface for hosting Python based web applications on top of the Apache web server. -Installation of mod_wsgi can now be performed in one of two ways. +Installation of mod_wsgi from source code can be performed in one of two +ways. -The first way of installing mod_wsgi is the traditional way that has -been used in the past, where it is installed as a module directly into your -Apache installation. +The first way of installing mod_wsgi is the traditional way that has been +used by many software packages. This is where it is installed as a module +directly into your Apache installation using the commands ``configure``, +``make`` and ``make install``, a method sometimes referred to by the +acyronym CMMI. The second and newest way of installing mod_wsgi is to install it as a -Python package into your Python installation. +Python package into your Python installation using the Python ``pip +install`` command. -This new way of installing mod_wsgi will compile not only the Apache -module for mod_wsgi, but will also install a set of Python modules and -an admin script for running up Apache directly from the command line -with an auto generated configuration. - -This later mechanism for running up Apache, which is referred to as the -mod_wsgi express version, provides a much simpler way of getting starting -with hosting your Python web application. +This newer way of installing mod_wsgi will compile not only the Apache +module for mod_wsgi, but will also install a Python module and admin script +for starting up a standalone instance of Apache directly from the command +line with an auto generated configuration. +This later mechanism for installing mod_wsgi using Python 'pip' is a much +simpler way of getting starting with hosting your Python web application. In particular, the new installation method makes it very easy to use Apache/mod_wsgi in a development environment without the need to perform any Apache configuration yourself. +On some platforms, this latter method is the only option supported when +using the operating system supplied Apache installation. For example, in +MacOS X Sierra, Apple has completely broken the ability to install third +party Apache modules using the ``apxs`` tool normally used for this task. +History suggests that Apple will never fix the problem as they have broken +things in the past in other ways and workarounds were required as they +never fixed those problems either. This time there is no easy workaround +as they no longer supply certain tools which are required to perform the +installation. + +Note that neither of the above methods for installing mod_wsgi is supported +on Windows and that the Windows platform is no longer actively supported. + System Requirements ------------------- -With either installation method for mod_wsgi, you obviously must have -Apache installed. +With either installation method for mod_wsgi, you must have Apache +installed. This must be a complete Apache installation. It is not enough to +have only the runtime packages for Apache installed. You must have the +corresponding development package for Apache installed, which contains the +Apache header files, as these are required to be able compile and install +third party Apache modules. -If running Linux, any corresponding developer variant of the specific -Apache package you are using also needs to be installed. This is required -in order to be able to compile mod_wsgi from source code. +Similarly with Python, you must have a complete Python installation which +includes the corresponding development package, which contains the header +files for the Python library. -For example, on Ubuntu Linux with Apache 2.2, if you were using the Apache -prefork MPM you would need both: +If you are running Debian or Ubuntu Linux with Apache 2.2 system packages, +and were using the Apache prefork MPM you would need both: * apache2-mpm-prefork * apache2-prefork-dev @@ -52,24 +71,41 @@ If instead you were using the Apache worker MPM, you would need both: * apache2-mpm-worker * apache2-threaded-dev -In general it is recommend you use the Apache worker MPM where you have -a choice, although mod_wsgi will work with both, as well as the event -and ITK MPM, plus winnt MPM on Windows. +If you are running Debian or Ubuntu Linux with Apache 2.4 system packages, +regardless of which Apache MPM is being used, you would need both: + +* apache2 +* apache2-dev + +If you are running RHEL, CentOS or Fedora, you would need both: + +* httpd +* httpd-devel + +If you are using the Software Collections Library (SCL) packages with +RHEL, CentOS or Fedora, you would need: + +* httpd24 -If you are running MacOS X, the Apache server and required developer -files for compiling mod_wsgi are already present. +If you are running MacOS X, you will need to have the Xcode command line +tools installed. These can be installed by running ``xcode-select --install``. Installation into Apache ------------------------ -For installation directly into your Apache installation, see the full -documentation at: +For installation directly into your Apache installation using the CMMI +method, see the full documentation at: * http://www.modwsgi.org/ -Also see the documentation if wishing to use mod_wsgi on Windows as the -method of installing direct into your Python installation will not work -on Windows. +Alternatively, use the following instructions to install mod_wsgi into your +Python installation and then either copy the mod_wsgi module into your +Apache installation, or configure Apache to use the mod_wsgi module from +the Python installation. + +When using this approach, you will still need to manually configure Apache +to have mod_wsgi loaded into Apache, and for it to know about your WSGI +application. Installation into Python ------------------------ @@ -83,8 +119,8 @@ can run:: This will compile mod_wsgi and install the resulting package into your Python installation. -If wishing to install an official release direct from PyPi, you can -instead run:: +If wishing to install an official release direct from the Python Package +Index (PyPi), you can instead run:: pip install mod_wsgi @@ -96,7 +132,9 @@ before performing the installation. Note that nothing will be copied into your Apache installation at this point. As a result, you do not need to run this as the root user unless installing it into a site wide Python installation rather than a Python -virtual environment. +virtual environment. It is recommended you always use Python virtual +environments and never install any Python package direct into the system +Python installation. To verify that the installation was successful, run the ``mod_wsgi-express`` script with the ``start-server`` command:: @@ -123,13 +161,13 @@ running on port 80. If you already have another web server running on port 8000, you can override the port to be used using the ``--port`` option:: - mod_wsgi-express start-server wsgi.py --port 8001 + mod_wsgi-express start-server wsgi.py --port 8080 For a complete list of options you can run:: mod_wsgi-express start-server --help -Further information on using the mod_wsgi express version see the main +For further information related to using ``mod_wsgi-express`` see the main mod_wsgi documentation. Non standard Apache installations @@ -143,8 +181,8 @@ shell script which performs additional actions which can only be performed as the ``root`` user. In the case of the ``httpd`` executable simply being renamed, the -executable will obviously not be found and mod_wsgi express will fail to -start at all. +executable will obviously not be found and ``mod_wsgi-express`` will fail +to start at all. In this case you should work out what the ``httpd`` executable was renamed to and use the ``--httpd-executable`` option to specify its real location. @@ -159,7 +197,7 @@ which performs additional actions before then executing the original need to use the location of the original ``httpd`` executable the shell script is in turn executing. -Running mod_wsgi express as root +Running mod_wsgi-express as root -------------------------------- The primary intention of mod_wsgi express is to make it easier for users @@ -179,7 +217,7 @@ user account you have created for running the Python web application:: --user www-data --group www-data This approach to running ``mod_wsgi-express`` will be fine so long as you -are using a process supervisor which expects the started process to remain +are using a process supervisor which expects the process being run to remain in the foreground and not daemonize. If however you are directly integrating into the system init scripts where @@ -195,7 +233,7 @@ In this case, instead of simply using the ``start-server`` command to --server-root=/etc/mod_wsgi-express-80 In running this command, it will not actually startup Apache. All it will do -is create the set of configuration files and startup script to be run. +is create the set of configuration files and the startup script to be run. So that these are not created in the default location of a directory under ``/tmp``, you should use the ``--server-root`` option to specify where they @@ -215,26 +253,26 @@ You can also restart the Apache instance as necessary using:: /etc/mod_wsgi-express-80/apachectl restart Using this approach, the original options you supplied to ``setup-server`` -will effectively be cached with the resulting configuration used each time. -If you need to update the set of options, run ``setup-server`` again with -the new set of options. +will be cached with the same configuration used each time. If you need to +update the set of options, run ``setup-server`` again with the new set of +options. Note that even taking all these steps, it is possible that running up -Apache as ``root`` using mod_wsgi express may fail on systems where SELinux -extensions are enabled. This is because the SELinux profile may not match -what is being expected for the way that Apache is being started, or +Apache as ``root`` using ``mod_wsgi-express`` may fail on systems where +SELinux extensions are enabled. This is because the SELinux profile may not +match what is being expected for the way that Apache is being started, or alternatively, the locations that Apache has been specified as being allowed to access, don't match where the directory specified using the ``--server-root`` directory was placed. You may therefore need to configure SELinux or move the directory used with ``--server-root`` to an allowed location. -Using mod_wsgi express with Django +Using mod_wsgi-express with Django ---------------------------------- -To use the mod_wsgi express version with Django, after having installed -the mod_wsgi package into your Python installation, edit your Django -settings module and add ``mod_wsgi.server`` to the list of installed apps. +To use ``mod_wsgi-express`` with Django, after having installed the +mod_wsgi package into your Python installation, edit your Django settings +module and add ``mod_wsgi.server`` to the list of installed apps. :: @@ -248,9 +286,9 @@ settings module and add ``mod_wsgi.server`` to the list of installed apps. 'mod_wsgi.server', ) -To prepare for running of the mod_wsgi express version, ensure that you -first collect up any Django static file assets into the directory specified -for them in the Django settings file:: +To prepare for running ``mod_wsgi-express``, ensure that you first collect +up any Django static file assets into the directory specified for them in +the Django settings file:: python manage.py collectstatic @@ -276,23 +314,65 @@ use the ``--setup-only`` option to the ``runmodwsgi`` management command. python manage.py runmodwsgi --setup-only --port=80 \ --user www-data --group www-data \ --server-root=/etc/mod_wsgi-express-80 - -Using mod_wsgi express with New Relic -------------------------------------- - -If using `New Relic <http://www.newrelic.com/>`_ for application -performance monitoring, and you already have the ``newrelic`` package -installed and your Python agent configuration file generated, you can use -the ``--with-newrelic`` option. - -You do not need to use the ``newrelic-admin`` script that New Relic -provides to wrap the execution of the server. You only need to set the -``NEW_RELIC_CONFIG_FILE`` environment variable to the location of your -agent configuration file. - -:: - - NEW_RELIC_CONFIG_FILE=`pwd`/newrelic.ini - export NEW_RELIC_CONFIG_FILE - - mod_wsgi-express start-server wsgi.py --with-newrelic + +This will setup all the required files and you can use ``apachectl`` to +start and stop the Apache instance as explained previously. + +Connecting into Apache installation +----------------------------------- + +If you want to use mod_wsgi in combination with your system Apache +installation, the CMMI method for installing mod_wsgi would normally be +used. If you are on MacOS X Sierra that is no longer possible. Even prior +to MacOS X Sierra, the System Integrity Protection (SIP) system of MacOS X, +prevented installing the mod_wsgi module into the Apache modules +directory. + +The CMMI installation method also involves a bit more work as you need to +separately download the mod_wsgi source code, run the ``configure`` tool +and then run ``make`` and ``make install``. + +The alternative to using the CMMI installation method is to use the Apache +mod_wsgi module created by running ``pip install``. This can be directly +referenced from the Apache configuration, or copied into the Apache modules +directory. + +To use the Apache mod_wsgi module from where ``pip install`` placed it, +run the command ``mod_wsgi-express module-config``. This will output +something like:: + + LoadModule wsgi_module /usr/local/lib/python2.7/site-packages/mod_wsgi/server/mod_wsgi-py27.so + WSGIPythonHome /usr/local/lib + +These are the directives needed to configure Apache to load the mod_wsgi +module and tell mod_wsgi where the Python installation directory or virtual +environment was located. + +This would be placed in the Apache ``httpd.conf`` file, or if the Linux +distribution separates out module configuration into a ``mods-available`` +directory, in the ``wsgi.load`` file within the ``mods-available`` +directory. In the latter case where a ``mods-available`` directory is used, +the module would then be enabled by running ``a2enmod wsgi``. If necessary +Apache can then be restarted to verify the module is loading correctly. You +can then configure Apache as necessary for your specific WSGI application. + +Note that because in this scenario the mod_wsgi module for Apache could be +located in a Python virtual environment, if you destroy the Python virtual +environment the module will also be deleted. In that case you would need to +ensure you recreated the Python virtual environment and reinstalled the +mod_wsgi package using ``pip``, or take out the mod_wsgi configuration from +Apache before restarting Apache or it will fail to startup. + +Instead of referencing the mod_wsgi module from the Python installation, +you can instead copy the mod_wsgi module into the Apache installation. To +do that, run the ``mod_wsgi-express install-module`` command, running it as +``root`` using ``sudo`` if necessary. This will output something like:: + + LoadModule wsgi_module modules/mod_wsgi-py27.so + WSGIPythonHome /usr/local/lib + +This is similar to above except that the mod_wsgi module was copied to the +Apache modules directory first and the ``LoadModule`` directive references +it from that location. You should take these lines and configure Apache in +the same was as described above. Do note that copying the module like this +will not work on recent versions of MacOS X due to the SIP feature of MacOS X. @@ -434,19 +434,22 @@ if (not get_python_config('Py_ENABLE_SHARED') and # Now finally run distutils. +long_description = open('README.rst').read() + setup(name = 'mod_wsgi', version = _version(), description = 'Installer for Apache/mod_wsgi.', + long_description = long_description, author = 'Graham Dumpleton', author_email = 'Graham.Dumpleton@gmail.com', maintainer = 'Graham Dumpleton', maintainer_email = 'Graham.Dumpleton@gmail.com', url = 'http://www.modwsgi.org/', - #bugtrack_url = 'https://github.com/GrahamDumpleton/mod_wsgi/issues', + bugtrack_url = 'https://github.com/GrahamDumpleton/mod_wsgi/issues', license = 'Apache License, Version 2.0', platforms = [], download_url = None, - classifiers= [ + classifiers = [ 'Development Status :: 6 - Mature', 'License :: OSI Approved :: Apache Software License', 'Operating System :: MacOS :: MacOS X', @@ -460,9 +463,11 @@ setup(name = 'mod_wsgi', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3.3', 'Programming Language :: Python :: 3.4', + 'Programming Language :: Python :: 3.5', 'Topic :: Internet :: WWW/HTTP :: WSGI', 'Topic :: Internet :: WWW/HTTP :: WSGI :: Server' ], + keywords = 'mod_wsgi wsgi apache', packages = ['mod_wsgi', 'mod_wsgi.server', 'mod_wsgi.server.management', 'mod_wsgi.server.management.commands', 'mod_wsgi.docs', 'mod_wsgi.images'], |