Mod Wsgi Documentation Release 4.9.0
Total Page:16
File Type:pdf, Size:1020Kb
mod_wsgi Documentation Release 4.9.0 Graham Dumpleton Aug 03, 2021 Contents 1 Project Status 3 2 Security Issues 5 3 Getting Started 7 4 Requirements 9 5 Installation 11 6 Troubleshooting 13 7 User Guides 15 8 Configuration 133 9 Finding Help 159 10 Reporting Bugs 161 11 Contributing 163 12 Source Code 167 13 Release Notes 169 i ii mod_wsgi Documentation, Release 4.9.0 The mod_wsgi package implements a simple to use Apache module which can host any Python web application which supports the Python WSGI specification. The package can be installed in two different ways depending on your requirements. The first is as a traditional Apache module installed into an existing Apache installation. Following this path you will need to manually configure Apache to load mod_wsgi and pass through web requests to your WSGI application. The second way of installing mod_wsgi is to install it from PyPI using the Python pip command. This builds and installs mod_wsgi into your Python installation or virtual environment. The program mod_wsgi-express will then be available, allowing you to run up Apache with mod_wsgi from the command line with an automatically generated configuration. This approach does not require you to perform any configuration of Apache yourself. Both installation types are suitable for production deployments. The latter approach using mod_wsgi-express is the best solution if wishing to use Apache and mod_wsgi within a Docker container to host your WSGI application. It is also a better choice when using mod_wsgi during the development of your Python web application as you will be able to run it directly from your terminal. Contents 1 mod_wsgi Documentation, Release 4.9.0 2 Contents CHAPTER 1 Project Status The mod_wsgi project is still being developed and maintained. The available time of the sole developer is however limited. As a result, progress may appear to be slow. In general, the documentation is in a bit of a mess right now and somewhat outdated, so if you can’t find something then ask on the mod_wsgi mailing list for help. Also check out the Release Notes as they at least are being updated. A lot of the more recent changes are being made with the aim of making it a lot easier to deploy Apache with mod_wsgi in Docker based environments. Changes included the ability to install mod_wsgi using pip, along with an admin command called mod_wsgi-express which provides a really simple way of starting up Apache and mod_wsgi from the command line with an automatically generated configuration. 3 mod_wsgi Documentation, Release 4.9.0 4 Chapter 1. Project Status CHAPTER 2 Security Issues Due to security issues in versions of mod_wsgi up to and including version 3.4, ensure that you are using version 3.5 or later. Release notes for versions containing security related fixes are: • Version 3.5 Because many Linux distributions still ship ancient out of date versions, which are not supported, it is highly rec- ommended you avoid using packaged binary versions provided by your Linux distribution. Instead install mod_wsgi from source code, ensuring you keep up to date with the most recent version. 5 mod_wsgi Documentation, Release 4.9.0 6 Chapter 2. Security Issues CHAPTER 3 Getting Started If starting out with mod_wsgi it is recommended you start out with a simple ‘Hello World’ type application. Do not attempt to use a Python web application dependent on a web framework such as Django, Flask or Pyramid until you have got a basic ‘Hello World’ application running first. The simpler WSGI application will validate that your mod_wsgi installation is working okay and that you at least understand the basics of configuring Apache. You can find a simple ‘Hello World’ WSGI application, along with setup instructions for the traditional way of setting up Apache and mod_wsgi, described in the Quick Configuration Guide. For a bit more in-depth information and additional examples see the Configuration Guidelines. Note that unless you are using Windows, where such a choice is not available, you should always use daemon mode of mod_wsgi. This is not the default mode, so you will need to ensure you follow the instructions to enable daemon mode. For a simpler way of running a Python WSGI application using mod_wsgi, also checkout mod_wsgi-express, details of which can currently be found at: https://pypi.python.org/pypi/mod_wsgi 7 mod_wsgi Documentation, Release 4.9.0 8 Chapter 3. Getting Started CHAPTER 4 Requirements The mod_wsgi package can be compiled for and used with most recent patch revisions of Apache 2.0, 2.2 or 2.4 on UNIX like systems, such as Linux and MacOS X, as well as Windows. It is highly recommended that you use Apache 2.4. Older versions of Apache have architectural design problems and sub optimal configuration defaults, that can result in excessive memory usage in certain circumstances. More recent mod_wsgi versions attempt to protect against these problems in Apache 2.0 and 2.2, however it is still better to use Apache 2.4. Any of the single threaded ‘prefork’ or multithreaded ‘worker’ and ‘event’ Apache MPMs can be used when running on UNIX like systems. Both Python 2 and 3 are supported. The minimum recommended versions of each being Python 2.6 and 3.3 respec- tively. The Python installation must have been installed in a way that shared libraries for Python are provided such that embedding of Python in another application is possible. The mod_wsgi package should be able to host any Python web application which complies with the WSGI specifi- cation (PEP 3333). The implementation is very strict with its interpretation of the WSGI specification. Other WSGI servers available aren’t as strict and allow Python web applications to run which do not comply with the WSGI speci- fication. If your Python web application doesn’t comply properly with the WSGI specification, then it may fail to run or may run sub optimally when using mod_wsgi. 9 mod_wsgi Documentation, Release 4.9.0 10 Chapter 4. Requirements CHAPTER 5 Installation The mod_wsgi package can be installed from source code or may also be available as a pre built binary package as part of your Linux distribution. Do be aware though that Linux distributions generally ship out of date versions of mod_wsgi and for long term support (LTS) versions of Linux can be anything up to about 5 years old. Those older versions are not supported in any way even though they are part of a so called LTS version of Linux. If you want support and want to ensure you have the most up to date and bug free version of mod_wsgi, you should consider building and installing mod_wsgi from the source code. For instructions on how to compile mod_wsgi from the source code for UNIX like operating systems such as Linux and MacOS X see: • Quick Installation Guide • Installation On MacOS X If you are on Windows, you should instead use: • https://github.com/GrahamDumpleton/mod_wsgi/blob/develop/win32/README.rst 11 mod_wsgi Documentation, Release 4.9.0 12 Chapter 5. Installation CHAPTER 6 Troubleshooting If you are having problems getting mod_wsgi to start up or do what you want it to do, first off ensure that you read the following documents: • Installation Issues • Configuration Issues • Application Issues You can also do some basic checking of your installation and configuration to validate that how it is setup is how you expect it to be. See the following document: • Checking Your Installation If none of the common issues match up with the problem you are seeing and are after other ideas, or you have the need to perform more low level debugging, check out the User Guides. 13 mod_wsgi Documentation, Release 4.9.0 14 Chapter 6. Troubleshooting CHAPTER 7 User Guides 7.1 Quick Installation Guide This document describes the steps for installing mod_wsgi on a UNIX system from the original source code. 7.1.1 Apache Requirements Apache 2.0, 2.2 or 2.4 can be used. For Apache 2.0, 2.2 and 2.4, the single threaded ‘prefork’ or multithreaded ‘worker’ Apache MPMs can be used. For Apache 2.4 the ‘event’ MPM can also be used. The version of Apache and its runtime libraries must have be compiled with support for threading. On Linux systems, if Apache has been installed from a package repository, you must have installed the corresponding Apache “dev” package as well. For most Linux distributions, the “dev” package for Apache 2.X is “apache2-dev” where the corresponding Apache package was “apache2”. Some systems however distinguish the “dev” package based on which MPM is used by Apache. As such, it may also be called “apache2-worker-dev” or “apache2-prefork-dev”. If using Apache 2.X, do not mix things up and install “apache-dev” by mistake, which is the “dev” package for Apache 1.3 called just “apache”. 7.1.2 Python Requirements Any Python 2.X version from Python 2.6 onwards can be used. For Python 3.X, you will need Python 3.3 or later. The version of Python being used must have been compiled with support for threading. On Linux systems, if Python has been installed from a package repository, you must have installed the corresponding Python “dev” package as well. Python should preferably be available as a shared library. If this is not the case then base runtime memory usage of mod_wsgi will be greater. 15 mod_wsgi Documentation, Release 4.9.0 7.1.3 Unpacking The Source Code Source code tar balls can be obtained from: • https://github.com/GrahamDumpleton/mod_wsgi/releases After having downloaded the tar ball for the version you want to use, unpack it with the command: tar xvfz mod_wsgi-X.Y.tar.gz Replace ‘X.Y’ with the actual version number for that being used.