WSGIScriptAlias

Description:

Maps a URL to a filesystem location and designates the target as a WSGI script.

Syntax:

WSGIScriptAlias URL-path file-path|directory-path [ options ]

Context:

server config, virtual host

The WSGIScriptAlias directive behaves in the same manner as the Alias directive, except that it additionally marks the target directory as containing WSGI scripts, or marks the specific file-path as a script, that should be processed by mod_wsgi’s wsgi-script handler.

Where the target is a directory-path, URLs with a case-sensitive (%-decoded) path beginning with URL-path will be mapped to scripts contained in the indicated directory.

For example:

WSGIScriptAlias /wsgi-scripts/ /web/wsgi-scripts/

A request for http://www.example.com/wsgi-scripts/name in this case would cause the server to run the WSGI application defined in /web/wsgi-scripts/name. This configuration is essentially equivalent to:

Alias /wsgi-scripts/ /web/wsgi-scripts/
<Location /wsgi-scripts>
SetHandler wsgi-script
Options +ExecCGI
</Location>

The <Location> form above is shown only to illustrate what WSGIScriptAlias does internally. The recommended pattern when you need to apply directives to the script directory is the <Directory> form shown below.

Where the target is a file-path, URLs with a case-sensitive (%-decoded) path beginning with URL-path will be mapped to the script defined by the file-path.

For example:

WSGIScriptAlias /name /web/wsgi-scripts/name

A request for http://www.example.com/name in this case would cause the server to run the WSGI application defined in /web/wsgi-scripts/name.

A WSGI application can also be mounted at the root of the site by using / as the URL-path:

WSGIScriptAlias / /web/wsgi-scripts/myapp.wsgi

In this case all requests to the site will be dispatched to the specified WSGI script file.

The .wsgi extension shown here is a convention only — when WSGIScriptAlias is used, the script is identified by its full file path and any extension (or none) is acceptable. The .wsgi convention is used to avoid clashing with any pre-existing AddHandler directive that may already map .py files to a different handler such as cgi-script. If you know there is no such conflict, the script file can use .py like any other Python file.

If possible you should avoid placing WSGI scripts under the DocumentRoot in order to avoid accidentally revealing their source code if the configuration is ever changed. The WSGIScriptAlias makes this easy by mapping a URL and designating the location of any WSGI scripts at the same time. If you do choose to place your WSGI scripts in a directory already accessible to clients, do not use WSGIScriptAlias. Instead, use Directory, SetHandler and Options as in:

<Directory /usr/local/apache/htdocs/wsgi-scripts>
SetHandler wsgi-script
Options ExecCGI
</Directory>

This is necessary since multiple URL-paths can map to the same filesystem location, potentially bypassing the WSGIScriptAlias and revealing the source code of the WSGI scripts if they are not restricted by a Directory section.

Options which can be supplied to the WSGIScriptAlias directive are:

process-group=name

Defines which process group the WSGI application will be executed in. All WSGI applications within the same process group will execute within the context of the same group of daemon processes.

If the name is set to be %{GLOBAL} the process group name will be set to the empty string. Any WSGI applications in the global process group will always be executed within the context of the standard Apache child processes. Such WSGI applications will incur the least runtime overhead, however, they will share the same process space with other Apache modules such as PHP, as well as the process being used to serve up static file content. Running WSGI applications within the standard Apache child processes will also mean the application will run as the user that Apache would normally run as.

If the name takes the form %{ENV:variable}, the process group name will be taken from the named Apache environment variable.

application-group=name

Defines which application group a WSGI application or set of WSGI applications belongs to. All WSGI applications within the same application group will execute within the context of the same Python sub interpreter of the process handling the request.

If the name is set to be %{GLOBAL} the application group will be set to the empty string. Any WSGI applications in the global application group will always be executed within the context of the main Python interpreter of the process handling the request. Forcing a WSGI application to run within the main interpreter can be necessary when a third party C extension module for Python has used the simplified threading API for manipulation of the Python GIL and thus will not run correctly within any additional sub interpreters created by Python.

If the name takes the form %{ENV:variable}, the application group name will be taken from the named Apache environment variable.

When the %{ENV:variable} form is used, the named environment variable is looked up via the internal Apache notes and subprocess environment data structures, and (if not found there) via getenv() from the Apache server process.

Environment variables accessible via the %{ENV} reference can be set in the Apache configuration using directives such as SetEnv and RewriteRule.

If both process-group and application-group options are set, the WSGI script file will be pre-loaded when the process it is to run in is started, rather than being lazily loaded on the first request. This removes the per-process startup delay that would otherwise be paid by the first request to reach each process.

For configurations that do not use WSGIScriptAlias, or where you want to preload additional script files alongside the main one, see the WSGIImportScript directive.