diff --git a/django/conf/global_settings.py b/django/conf/global_settings.py index 29c9812..18a9d38 100644 --- a/django/conf/global_settings.py +++ b/django/conf/global_settings.py @@ -404,6 +404,11 @@ X_FRAME_OPTIONS = 'SAMEORIGIN' USE_X_FORWARDED_HOST = False +# The import name of the WSGI application. If this is `None` the default +# 'django.core.handlers.wsgi.application' is used. Otherwise this shall +# point to an actual WSGI application. +WSGI_APPLICATION = None + ############## # MIDDLEWARE # ############## diff --git a/django/conf/project_template/settings.py b/django/conf/project_template/settings.py index b92c116..9eb91f7 100644 --- a/django/conf/project_template/settings.py +++ b/django/conf/project_template/settings.py @@ -99,6 +99,9 @@ MIDDLEWARE_CLASSES = ( ROOT_URLCONF = '{{ project_name }}.urls' +# The WSGI application used by Django's runserver etc. +WSGI_APPLICATION = '{{ project_name }}.wsgi.application' + TEMPLATE_DIRS = ( # Put strings here, like "/home/html/django_templates" or "C:/www/django/templates". # Always use forward slashes, even on Windows. diff --git a/django/conf/project_template/wsgi.py b/django/conf/project_template/wsgi.py new file mode 100644 index 0000000..7e37f60 --- /dev/null +++ b/django/conf/project_template/wsgi.py @@ -0,0 +1,25 @@ +""" +WSGI config for {{ project_name }} project. + +This module contains the actual WSGI application to be used by Django's +development server and the production environment as the global variable +named ``application`` and is enabled by setting the ``WSGI_APPLICATION`` +setting to '{{ project_name }}.wsgi.application'. + +Of course usually you would have an actual Django WSGI application here, +but it also might make sense to replace the whole Django WSGI application +with a custom one that later delegates to the Django one (for instance if +you want to combine a Django application with an application of another +framework). +""" +from django.core.management import setup_settings + +settings = setup_settings(__name__) + +# The application object is used by the development server +# as well as a WSGI server configured to use this file. +from django.core.handlers.wsgi import application + +# Apply other WSGI middlewares here. +# from helloworld.wsgi import HelloWorldApplication +# application = HelloWorldApplication(application) diff --git a/django/contrib/staticfiles/handlers.py b/django/contrib/staticfiles/handlers.py index 962b835..d9f6833 100644 --- a/django/contrib/staticfiles/handlers.py +++ b/django/contrib/staticfiles/handlers.py @@ -12,7 +12,9 @@ class StaticFilesHandler(WSGIHandler): WSGI middleware that intercepts calls to the static files directory, as defined by the STATIC_URL setting, and serves those files. """ - def __init__(self, application, base_dir=None): + def __init__(self, application, base_dir=None, enabled=True): + # If not enabled this directly proxies to the given application. + self.enabled = enabled self.application = application if base_dir: self.base_dir = base_dir @@ -63,6 +65,6 @@ class StaticFilesHandler(WSGIHandler): return super(StaticFilesHandler, self).get_response(request) def __call__(self, environ, start_response): - if not self._should_handle(environ['PATH_INFO']): - return self.application(environ, start_response) - return super(StaticFilesHandler, self).__call__(environ, start_response) + if self.enabled and self._should_handle(environ['PATH_INFO']): + return super(StaticFilesHandler, self).__call__(environ, start_response) + return self.application(environ, start_response) diff --git a/django/contrib/staticfiles/management/commands/runserver.py b/django/contrib/staticfiles/management/commands/runserver.py index c6e56d2..d4e332c 100644 --- a/django/contrib/staticfiles/management/commands/runserver.py +++ b/django/contrib/staticfiles/management/commands/runserver.py @@ -21,7 +21,5 @@ class Command(BaseRunserverCommand): handler = super(Command, self).get_handler(*args, **options) use_static_handler = options.get('use_static_handler', True) insecure_serving = options.get('insecure_serving', False) - if (settings.DEBUG and use_static_handler or - (use_static_handler and insecure_serving)): - handler = StaticFilesHandler(handler) - return handler + enabled = use_static_handler and (settings.DEBUG or insecure_serving) + return StaticFilesHandler(handler, enabled=enabled) diff --git a/django/core/handlers/base.py b/django/core/handlers/base.py index b7c0ff8..3606e18 100644 --- a/django/core/handlers/base.py +++ b/django/core/handlers/base.py @@ -242,8 +242,8 @@ def get_script_name(environ): Returns the equivalent of the HTTP request's SCRIPT_NAME environment variable. If Apache mod_rewrite has been used, returns what would have been the script name prior to any rewriting (so it's the script name as seen - from the client's perspective), unless FORCE_SCRIPT_NAME is set (to - anything). + from the client's perspective), unless the FORCE_SCRIPT_NAME setting is + set (to anything). """ from django.conf import settings if settings.FORCE_SCRIPT_NAME is not None: diff --git a/django/core/handlers/wsgi.py b/django/core/handlers/wsgi.py index a816cad..5d58102 100644 --- a/django/core/handlers/wsgi.py +++ b/django/core/handlers/wsgi.py @@ -1,3 +1,4 @@ +from __future__ import with_statement import sys from threading import Lock try: @@ -7,10 +8,12 @@ except ImportError: from django import http from django.core import signals +from django.core.exceptions import ImproperlyConfigured from django.core.handlers import base from django.core.urlresolvers import set_script_prefix from django.utils import datastructures from django.utils.encoding import force_unicode, iri_to_uri +from django.utils.importlib import import_module from django.utils.log import getLogger logger = getLogger('django.request') @@ -124,6 +127,7 @@ class LimitedStream(object): self.buffer = sio.read() return line + class WSGIRequest(http.HttpRequest): def __init__(self, environ): script_name = base.get_script_name(environ) @@ -202,13 +206,12 @@ class WSGIRequest(http.HttpRequest): FILES = property(_get_files) REQUEST = property(_get_request) + class WSGIHandler(base.BaseHandler): initLock = Lock() request_class = WSGIRequest def __call__(self, environ, start_response): - from django.conf import settings - # Set up middleware if needed. We couldn't do this earlier, because # settings weren't available. if self._request_middleware is None: @@ -254,3 +257,39 @@ class WSGIHandler(base.BaseHandler): start_response(status, response_headers) return response +application = WSGIHandler() + + +class DjangoWSGIApplication(object): + """ + Implements a proxy to the actual WSGI application as configured + by the user in settings.WSGI_APPLICATION which will usually be the + `application`, optionally with middlewares applied. + """ + def __init__(self): + self._instance = None + self._instance_lock = Lock() + + def _load_application(self): + from django.conf import settings + app_path = getattr(settings, 'WSGI_APPLICATION') + if app_path is None: + return application + try: + module_name, attr = app_path.rsplit('.', 1) + return getattr(import_module(module_name), attr) + except (ImportError, AttributeError), e: + raise ImproperlyConfigured("WSGI application '%s' could not " + "be loaded: %s" % (app_path, e)) + + def __call__(self, environ, start_response): + # Non-atomic check, avoids taking a lock at each call of this method + if self._instance is None: + with self._instance_lock: + # Atomic check, prevents concurrent initialization of self._instance + if self._instance is None: + self._instance = self._load_application() + return self._instance(environ, start_response) + +# the proxy used in deployment +django_application = DjangoWSGIApplication() diff --git a/django/core/management/__init__.py b/django/core/management/__init__.py index ea494c7..9ee35d3 100644 --- a/django/core/management/__init__.py +++ b/django/core/management/__init__.py @@ -392,10 +392,10 @@ def setup_environ(settings_mod, original_settings_path=None): # way. For example, if this file (manage.py) lives in a directory # "myproject", this code would add "/path/to/myproject" to sys.path. if '__init__.py' in settings_mod.__file__: - p = os.path.dirname(settings_mod.__file__) + path = os.path.dirname(settings_mod.__file__) else: - p = settings_mod.__file__ - project_directory, settings_filename = os.path.split(p) + path = settings_mod.__file__ + project_directory, settings_filename = os.path.split(path) if project_directory == os.curdir or not project_directory: project_directory = os.getcwd() project_name = os.path.basename(project_directory) @@ -425,6 +425,42 @@ def setup_environ(settings_mod, original_settings_path=None): return project_directory + +def setup_settings(path): + """ + Configures the settings first by looking at the environment variable + DJANGO_SETTINGS_MODULE or if that fail tries to find it with the + given module path. + + Example: + + from django.core.management import setup_settings + + setup_settings(__name__) + setup_settings('wsgi') + setup_settings('mysite.wsgi') + """ + try: + # Check if DJANGO_SETTINGS_MODULE is already given + settings_module = os.environ['DJANGO_SETTINGS_MODULE'] + if not settings_module: + raise KeyError + settings = import_module(settings_module) + except KeyError: + # Or try importing the settings module two levels up, + # so if name is 'mysite.wsgi', it'll try 'mysite.settings' + try: + settings = import_module('settings', path) + except ImportError: + # two levels up because name contains the submodule + settings = import_module('..settings', path) + setup_environ(settings) + + # Return the settings module + from django.conf import settings + return settings + + def execute_from_command_line(argv=None): """ A simple method that runs a ManagementUtility. diff --git a/django/core/management/commands/runserver.py b/django/core/management/commands/runserver.py index 2e693e7..c84bf30 100644 --- a/django/core/management/commands/runserver.py +++ b/django/core/management/commands/runserver.py @@ -5,7 +5,7 @@ import sys import socket from django.core.management.base import BaseCommand, CommandError -from django.core.handlers.wsgi import WSGIHandler +from django.core.handlers.wsgi import django_application from django.core.servers.basehttp import AdminMediaHandler, run, WSGIServerException from django.utils import autoreload @@ -37,7 +37,7 @@ class BaseRunserverCommand(BaseCommand): """ Returns the default WSGI handler for the runner. """ - return WSGIHandler() + return django_application def handle(self, addrport='', *args, **options): self.use_ipv6 = options.get('use_ipv6') diff --git a/django/core/servers/fastcgi.py b/django/core/servers/fastcgi.py index 9f80d2b..442df44 100644 --- a/django/core/servers/fastcgi.py +++ b/django/core/servers/fastcgi.py @@ -139,7 +139,7 @@ def runfastcgi(argset=[], **kwargs): return False # Prep up and go - from django.core.handlers.wsgi import WSGIHandler + from django.core.handlers.wsgi import django_application if options["host"] and options["port"] and not options["socket"]: wsgi_opts['bindAddress'] = (options["host"], int(options["port"])) @@ -178,7 +178,7 @@ def runfastcgi(argset=[], **kwargs): fp.write("%d\n" % os.getpid()) fp.close() - WSGIServer(WSGIHandler(), **wsgi_opts).run() + WSGIServer(django_application, **wsgi_opts).run() if __name__ == '__main__': runfastcgi(sys.argv[1:]) diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt index 1f769cb..b4a0c4f 100644 --- a/docs/howto/deployment/fastcgi.txt +++ b/docs/howto/deployment/fastcgi.txt @@ -5,7 +5,7 @@ How to use Django with FastCGI, SCGI, or AJP .. highlight:: bash Although the current preferred setup for running Django is :doc:`Apache with -mod_wsgi `, many people use shared hosting, on +mod_wsgi `, many people use shared hosting, on which protocols such as FastCGI, SCGI or AJP are the only viable options. In some setups, these protocols may provide better performance than mod_wsgi_. diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index fdfce3e..113f606 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -9,13 +9,12 @@ ways to easily deploy Django: .. toctree:: :maxdepth: 1 - modwsgi - uwsgi + wsgi/index fastcgi mod_python (deprecated) If you're new to deploying Django and/or Python, we'd recommend you try -:doc:`mod_wsgi ` first. In most cases it'll be +:doc:`mod_wsgi ` first. In most cases it'll be the easiest, fastest, and most stable deployment choice. .. seealso:: diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt index f5030e9..0d9edd3 100644 --- a/docs/howto/deployment/modpython.txt +++ b/docs/howto/deployment/modpython.txt @@ -7,14 +7,14 @@ How to use Django with Apache and mod_python Support for mod_python has been deprecated, and will be removed in Django 1.5. If you are configuring a new deployment, you are strongly encouraged to consider using :doc:`mod_wsgi - ` or any of the other :doc:`supported + ` or any of the other :doc:`supported backends `. .. highlight:: apache The `mod_python`_ module for Apache_ can be used to deploy Django to a production server, although it has been mostly superseded by the simpler -:doc:`mod_wsgi deployment option `. +:doc:`mod_wsgi deployment option `. mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within Apache and loads Python code into memory when the server starts. Code stays in diff --git a/docs/howto/deployment/modwsgi.txt b/docs/howto/deployment/modwsgi.txt deleted file mode 100644 index d268334..0000000 --- a/docs/howto/deployment/modwsgi.txt +++ /dev/null @@ -1,147 +0,0 @@ -========================================== -How to use Django with Apache and mod_wsgi -========================================== - -Deploying Django with Apache_ and `mod_wsgi`_ is the recommended way to get -Django into production. - -.. _Apache: http://httpd.apache.org/ -.. _mod_wsgi: http://code.google.com/p/modwsgi/ - -mod_wsgi is an Apache module which can be used to host any Python application -which supports the Python WSGI interface described in :pep:`3333`, including -Django. Django will work with any version of Apache which supports mod_wsgi. - -The `official mod_wsgi documentation`_ is fantastic; it's your source for all -the details about how to use mod_wsgi. You'll probably want to start with the -`installation and configuration documentation`_. - -.. _official mod_wsgi documentation: http://code.google.com/p/modwsgi/ -.. _installation and configuration documentation: http://code.google.com/p/modwsgi/wiki/InstallationInstructions - -Basic configuration -=================== - -Once you've got mod_wsgi installed and activated, edit your ``httpd.conf`` file -and add:: - - WSGIScriptAlias / /path/to/mysite/apache/django.wsgi - -The first bit above is the url you want to be serving your application at (``/`` -indicates the root url), and the second is the location of a "WSGI file" -- see -below -- on your system, usually inside of your project. This tells Apache -to serve any request below the given URL using the WSGI application defined by that file. - -Next we'll need to actually create this WSGI application, so create the file -mentioned in the second part of ``WSGIScriptAlias`` and add:: - - import os - import sys - - os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings' - - import django.core.handlers.wsgi - application = django.core.handlers.wsgi.WSGIHandler() - -If your project is not on your ``PYTHONPATH`` by default you can add:: - - path = '/path/to/mysite' - if path not in sys.path: - sys.path.append(path) - -just below the ``import sys`` line to place your project on the path. Remember to -replace 'mysite.settings' with your correct settings file, and '/path/to/mysite' -with your own project's location. - -.. _serving-files: - -Serving files -============= - -Django doesn't serve files itself; it leaves that job to whichever Web -server you choose. - -We recommend using a separate Web server -- i.e., one that's not also running -Django -- for serving media. Here are some good choices: - - * lighttpd_ - * Nginx_ - * TUX_ - * A stripped-down version of Apache_ - * Cherokee_ - -If, however, you have no option but to serve media files on the same Apache -``VirtualHost`` as Django, you can set up Apache to serve some URLs as -static media, and others using the mod_wsgi interface to Django. - -This example sets up Django at the site root, but explicitly serves -``robots.txt``, ``favicon.ico``, any CSS file, and anything in the -``/static/`` and ``/media/`` URL space as a static file. All other URLs -will be served using mod_wsgi:: - - Alias /robots.txt /usr/local/wsgi/static/robots.txt - Alias /favicon.ico /usr/local/wsgi/static/favicon.ico - - AliasMatch ^/([^/]*\.css) /usr/local/wsgi/static/styles/$1 - - Alias /media/ /usr/local/wsgi/media/ - Alias /static/ /usr/local/wsgi/static/ - - - Order deny,allow - Allow from all - - - - Order deny,allow - Allow from all - - - WSGIScriptAlias / /usr/local/wsgi/scripts/django.wsgi - - - Order allow,deny - Allow from all - - -.. _lighttpd: http://www.lighttpd.net/ -.. _Nginx: http://wiki.nginx.org/Main -.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server -.. _Apache: http://httpd.apache.org/ -.. _Cherokee: http://www.cherokee-project.com/ - -.. More details on configuring a mod_wsgi site to serve static files can be found -.. in the mod_wsgi documentation on `hosting static files`_. - -.. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files - -.. _serving-the-admin-files: - -Serving the admin files -======================= - -Note that the Django development server automagically serves the static files -of the admin app, but this is not the case when you use any other server -arrangement. You're responsible for setting up Apache, or whichever media -server you're using, to serve the admin files. - -The admin files live in (:file:`django/contrib/admin/static/admin`) of the -Django distribution. - -We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle -the admin files, but here are two other approaches: - - 1. Create a symbolic link to the admin static files from within your - document root. - - 2. Or, copy the admin static files so that they live within your Apache - document root. - -Details -======= - -For more details, see the `mod_wsgi documentation on Django integration`_, -which explains the above in more detail, and walks through all the various -options you've got when deploying under mod_wsgi. - -.. _mod_wsgi documentation on Django integration: http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango diff --git a/docs/howto/deployment/uwsgi.txt b/docs/howto/deployment/uwsgi.txt deleted file mode 100644 index 11cb51c..0000000 --- a/docs/howto/deployment/uwsgi.txt +++ /dev/null @@ -1,255 +0,0 @@ -============================ -How to use Django with uWSGI -============================ - -.. highlight:: bash - -uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application -container server coded in pure C. - -It also provides a fast `caching framework`_ but its documentation is not the -purpose of this document. - -.. _uWSGI: http://projects.unbit.it/uwsgi/ -.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework - - -Prerequisite: uWSGI -=================== - -The wiki describes several `installation procedures`_. Using pip, the python -package manager, installing any uWSGI version can be done with one command -line. For example:: - - # install current stable version - pip install uwsgi - - # or install LTS (long term support) - pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz - -.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install - -Prerequisite: general concept -============================= - -uWSGI model ------------ - -uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache) -communicates with a django-uwsgi "worker" process to serve dynamic contents. -The Web server can communicate with the uWSGI process either: - -* directly by the uWSGI protocol through a socket created by uWSGI, -* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI. - -In the first case: the Web server can do uWSGI protocol (often with a -module). It can then use either a Unix domain socket (a "named pipe" on Win32 -systems), or it can use a TCP socket. What you choose is a matterr of -preference. Usually, a TCP socket is easier because connecting to a port -doesn't require special permissions. - -In the second case, the Web server doesn't need to do uWSGI protocol. It just -needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI. -The procedure is the same than proxying any HTTP server. Note that the Web -server is a "reverse proxy" in this case. - -Configuring the uWSGI server ----------------------------- - -In any case, when you set up your Web server, you'll just need to point its -uwsgi or proxy module to the host/port or socket you specified when starting -the uWSGI server. - -.. admonition:: Choosing the socket - - The easiest is to set the socket to a high level (>49152) local port like - 127.0.0.1:49152. If the socket is a file, the system administrator must - ensure that the Web server process has read, write and execute privileges - on that file. - -uWSGI is highly configurable and thus there are many ways to start the -process. For example, uwsgi version 0.9.6.8 provides a hundred switches. -This guide demonstrates the most important of them, but does not intent to -substitute the official manual and online documentation. - -uWSGI supports configuration through: - -* environment variables -* command line switches -* ldap -* ini files -* xml files -* yaml files - -Managing the uWSGI server -------------------------- - -The system administrator controls the worker process pool by sending signals -to the master process. For example, the unix kill command sends such signals. -uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain -text file containing just a process id. - -Starting the server -------------------- - -Starting an uWSGI server is the role of the system administrator, like -starting the Web server. It is *not* the role of the Web server to start the -uWSGI server. This means: - -* the uWSGI server can be restarted or reloaded independently from the Web - server, -* (except with Cheerokee), it is the role of the system administrator to make - uWSGI to start on boot or reboot: either through tools like supervisor or - daemontools, either directly at init level in a file like /etc/rc.local or - /etc/conf.d/local - -Managing uWSGI -============== - -Starting the server -------------------- - -Example command line for a Web server that understand the uWSGI protocol:: - - uwsgi --chdir=/path/to/your/project - --module='django.core.handlers.wsgi:WSGIHandler()' \ - --env DJANGO_SETTINGS_MODULE=settings \ - --master --pidfile=/tmp/project-master.pid \ - --socket=127.0.0.1:49152 \ # can also be a file - --processes=5 \ # number of worker processes - --uid=1000 --gid=2000 \ # if root, uwsgi can drop privileges - --harakiri=20 \ # respawn processes taking more than 20 seconds - --limit-as=128 \ # limit the project to 128 Megabytes - --max-requests=5000 \ # respawn processes after serving 5000 requests - --vacuum \ # clear environment on exit - --home=/path/to/virtual/env \ # optionnal path to a virtualenv - --daemonize=/var/log/uwsgi/yourproject.log # background the process - -Django specific options are: - -* ``chdir``: should be the path to your project -* ``module``: uwsgi module to use -* ``pythonpath``: optional path to your project virtualenv -* ``env``: should contain at least ``DJANGO_SETTINGS_MODULE`` - -Example ini configuration file:: - - [uwsgi] - chdir=/path/to/your/project - master=True - pidfile=/tmp/project-master.pid - vacuum=True - max-requests=5000 - deamonize=/var/log/uwsgi/yourproject.log - -Example ini configuration file usage:: - - uwsgi --ini uwsgi.ini - -Read more `uWSGI configuration examples -`_. - -.. admonition:: Massive application hosting - - `uWSGI emperor `_ is a special - uWSGI process that can manage many master processes at once. - -Reloading the daemon --------------------- - -As mentioned above, the uWSGI master process is one of the core component of -the uWSGI stack. The signal to brutally reload all the workers and the master -process is SIGTERM. Example command to brutally reload the uWSGI processes:: - - kill -TERM `cat /tmp/project-master.pid` - -Patching the daemon -------------------- - -One of the great advantages of uWSGI is its ability to gradually restart each -worker without loosing any request. - -For example, uWSGI can be signaled that worker should reload the code after -handling their current request (if any) from bash:: - - # using kill to send the signal - kill -HUP `cat /tmp/project-master.pid` - - # if uwsgi was started with --touch-reload=/tmp/somefile - touch /tmp/somefile - -Or from Python:: - - uwsgi.reload() - -Stopping the daemon -------------------- - -If you have the process running in the foreground, it's easy enough to stop it: -Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when -you're dealing with background processes, you'll need to resort to the Unix -``kill`` command. - -The ``kill`` is used to send a signal to the uWSGI master process. The -`uWSGI signals are documented online -`_. Example command to -completely stop the uWSGI stack:: - - kill -INT `cat /tmp/project-master.pid` - -HTTP server configuration -========================= - -Nginx setup ------------ - -Nginx provides the `uwsgi module `_ by -default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as -simple as setting it up to proxy requests:: - - location / { - uwsgi_pass 127.0.0.1:49152; - # in case of a socket file: - # uwsgi_pass unix:/tmp/yourproject.sock; - } - -Note that default uwsgi parameters should be included somewhere in your Nginx -configuration. For example:: - - http { - include uwsgi_params; - # [...] normal nginx configuration here - } - -Cherokee setup --------------- - -Cherokee setup is documented in the `official Cherokee uWSGI documentation -`_. - -Lighttpd setup --------------- - -`Lighttpd uwsgi module `_ is -still experimental. - -Troubleshooting -=============== - -As usual, the first things to do is to check the logs. This implies: - -* the web server log, which will indicate if it couldn't connect to the uWSGI - process, -* the uWSGI log, which will indicate if an exception was thrown. - -Typical gotchas: - -* If the socket is a file, the Web server process should have read, write and - execute permissions on the socket file. The ``--chmod-socket`` option can do - it. -* In some cases, for instance if uWSGI was started without ``--vacuum`` or - killed with ``SIGKILL``, it won't remove the socket and pidfile when it is - interrupted. It is safe to remove them manually and to start uWSGI again in - that case. -* uWSGI can start the process on the foreground, this will make errors easily - visible to the system administrator. diff --git a/docs/howto/deployment/wsgi/index.txt b/docs/howto/deployment/wsgi/index.txt new file mode 100644 index 0000000..a838cf6 --- /dev/null +++ b/docs/howto/deployment/wsgi/index.txt @@ -0,0 +1,70 @@ +=============== +How to use WSGI +=============== + +Django's prefered platform of deployment is WSGI -- the "Web Server Gateway +Interface" standard as defined in :pep:`333` for web servers and application +servers that communicate with web applications. + +Specifically, you can configure how WSGI is used by Django internally (e.g. +by the :djadmin:`runserver` management command) and externally when deploying +to one of the more commonly known platforms: + +.. toctree:: + :maxdepth: 1 + + modwsgi + uwsgi + +The ``application`` object +-------------------------- + +One key concept of deploying with WSGI is to specify a central ``application`` +object which the webserver uses to communicate with your code. That's why +it's commonly specified as an object called ``application`` in a Python +module usable by the server. + +Django ships such a WSGI application object in the +``django.core.handlers.wsgi`` module by default but offers further +configurability with the :setting:`WSGI_APPLICATION` setting. + +The ``WSGI_APPLICATION`` setting +-------------------------------- + +The :setting:`WSGI_APPLICATION` setting should point to a WSGI compatible +application object, specified as a dotted Python import path. By default the +:djadmin:`startproject` command creates a file called ``wsgi.py`` in the +project directory and automatically sets :setting:`WSGI_APPLICATION` to +``.wsgi``. Django will internally automatically use this +module's application object when serving pages with the +:djadmin:`development server `. + +For example the file generated by :djadmin:`startproject` contains:: + + from django.core.management import setup_settings + + settings = setup_settings(__name__) + + # The application object is used by the development server + # as well as a WSGI server configured to use this file. + from django.core.handlers.wsgi import application + +The call to ``setup_settings`` is required to make sure the settings are +configured correctly before importing the WSGI handler. + +To apply `WSGI middlewares`_ you can simple wrap the application object +in the same file:: + + from helloworld.wsgi import HelloWorldApplication + application = HelloWorldApplication(application) + +Of course usually you would have an actual Django WSGI application here, +but it also might make sense to replace the whole Django WSGI application +with a custom WSGI application that later delegates to the Django WSGI +application (for instance if you want to combine a Django application with +a WSGI application of another framework). + +In case the :setting:`WSGI_APPLICATION` setting is ``None`` Django will +automatically use the ``django.core.handlers.wsgi.application`` object. + +.. _`WSGI middlewares`: http://www.python.org/dev/peps/pep-0333/#middleware-components-that-play-both-sides diff --git a/docs/howto/deployment/wsgi/modwsgi.txt b/docs/howto/deployment/wsgi/modwsgi.txt new file mode 100644 index 0000000..af286f7 --- /dev/null +++ b/docs/howto/deployment/wsgi/modwsgi.txt @@ -0,0 +1,149 @@ +========================================== +How to use Django with Apache and mod_wsgi +========================================== + +Deploying Django with Apache_ and `mod_wsgi`_ is the recommended way to get +Django into production. + +.. _Apache: http://httpd.apache.org/ +.. _mod_wsgi: http://code.google.com/p/modwsgi/ + +mod_wsgi is an Apache module which can be used to host any Python application +which supports the Python WSGI interface described in :pep:`333`, including +Django. Django will work with any version of Apache which supports mod_wsgi. + +The `official mod_wsgi documentation`_ is fantastic; it's your source for all +the details about how to use mod_wsgi. You'll probably want to start with the +`installation and configuration documentation`_. + +.. _official mod_wsgi documentation: http://code.google.com/p/modwsgi/ +.. _installation and configuration documentation: http://code.google.com/p/modwsgi/wiki/InstallationInstructions + +Basic configuration +=================== + +Once you've got mod_wsgi installed and activated, edit your ``httpd.conf`` +file and add:: + + WSGIScriptAlias / /path/to/mysite/wsgi.py + +The first bit above is the url you want to be serving your application at +(``/`` indicates the root url), and the second is the location of a "WSGI +file" -- see below -- on your system, usually inside of your project. This +tells Apache to serve any request below the given URL using the WSGI +application defined by that file. + +Next we'll need to actually create this WSGI application, so create the file +mentioned in the second part of ``WSGIScriptAlias`` and add:: + + import sys + from django.core.management import setup_settings + + setup_settings(__name__) + + # The application object is used by the development server + # as well as a WSGI server configured to use this file. + from django.core.handlers.wsgi import application + +If your project is not on your ``PYTHONPATH`` by default you can add:: + + path = '/path/to/mysite' + if path not in sys.path: + sys.path.append(path) + +just below the ``import sys`` line to place your project on the path. +Remember to replace 'mysite.settings' with your correct settings file, +and ``'/path/to/mysite'`` with your own project's location. + +.. _serving-files: + +Serving files +============= + +Django doesn't serve files itself; it leaves that job to whichever Web +server you choose. + +We recommend using a separate Web server -- i.e., one that's not also running +Django -- for serving media. Here are some good choices: + + * lighttpd_ + * Nginx_ + * TUX_ + * A stripped-down version of Apache_ + * Cherokee_ + +If, however, you have no option but to serve media files on the same Apache +``VirtualHost`` as Django, you can set up Apache to serve some URLs as +static media, and others using the mod_wsgi interface to Django. + +This example sets up Django at the site root, but explicitly serves +``robots.txt``, ``favicon.ico``, any CSS file, and anything in the +``/static/`` and ``/media/`` URL space as a static file. All other URLs +will be served using mod_wsgi:: + + Alias /robots.txt /usr/local/wsgi/static/robots.txt + Alias /favicon.ico /usr/local/wsgi/static/favicon.ico + + AliasMatch ^/([^/]*\.css) /usr/local/wsgi/static/styles/$1 + + Alias /media/ /usr/local/wsgi/media/ + Alias /static/ /usr/local/wsgi/static/ + + + Order deny,allow + Allow from all + + + + Order deny,allow + Allow from all + + + WSGIScriptAlias / /usr/local/wsgi/scripts/django.wsgi + + + Order allow,deny + Allow from all + + +.. _lighttpd: http://www.lighttpd.net/ +.. _Nginx: http://wiki.nginx.org/Main +.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server +.. _Apache: http://httpd.apache.org/ +.. _Cherokee: http://www.cherokee-project.com/ + +.. More details on configuring a mod_wsgi site to serve static files can be found +.. in the mod_wsgi documentation on `hosting static files`_. + +.. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files + +.. _serving-the-admin-files: + +Serving the admin files +======================= + +Note that the Django development server automagically serves the static files +of the admin app, but this is not the case when you use any other server +arrangement. You're responsible for setting up Apache, or whichever media +server you're using, to serve the admin files. + +The admin files live in (:file:`django/contrib/admin/static/admin`) of the +Django distribution. + +We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle +the admin files, but here are two other approaches: + + 1. Create a symbolic link to the admin static files from within your + document root. + + 2. Or, copy the admin static files so that they live within your Apache + document root. + +Details +======= + +For more details, see the `mod_wsgi documentation on Django integration`_, +which explains the above in more detail, and walks through all the various +options you've got when deploying under mod_wsgi. + +.. _mod_wsgi documentation on Django integration: http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango diff --git a/docs/howto/deployment/wsgi/uwsgi.txt b/docs/howto/deployment/wsgi/uwsgi.txt new file mode 100644 index 0000000..d3e631e --- /dev/null +++ b/docs/howto/deployment/wsgi/uwsgi.txt @@ -0,0 +1,256 @@ +============================ +How to use Django with uWSGI +============================ + +.. highlight:: bash + +uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application +container server coded in pure C. + +It also provides a fast `caching framework`_ but its documentation is not the +purpose of this document. + +.. _uWSGI: http://projects.unbit.it/uwsgi/ +.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework + + +Prerequisite: uWSGI +=================== + +The wiki describes several `installation procedures`_. Using pip, the python +package manager, installing any uWSGI version can be done with one command +line. For example:: + + # install current stable version + pip install uwsgi + + # or install LTS (long term support) + pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz + +.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install + +Prerequisite: general concept +============================= + +uWSGI model +----------- + +uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache) +communicates with a django-uwsgi "worker" process to serve dynamic contents. +The Web server can communicate with the uWSGI process either: + +* directly by the uWSGI protocol through a socket created by uWSGI, +* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI. + +In the first case: the Web server can do uWSGI protocol (often with a +module). It can then use either a Unix domain socket (a "named pipe" on Win32 +systems), or it can use a TCP socket. What you choose is a matterr of +preference. Usually, a TCP socket is easier because connecting to a port +doesn't require special permissions. + +In the second case, the Web server doesn't need to do uWSGI protocol. It just +needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI. +The procedure is the same than proxying any HTTP server. Note that the Web +server is a "reverse proxy" in this case. + +Configuring the uWSGI server +---------------------------- + +In any case, when you set up your Web server, you'll just need to point its +uwsgi or proxy module to the host/port or socket you specified when starting +the uWSGI server. + +.. admonition:: Choosing the socket + + The easiest is to set the socket to a high level (>49152) local port like + 127.0.0.1:49152. If the socket is a file, the system administrator must + ensure that the Web server process has read, write and execute privileges + on that file. + +uWSGI is highly configurable and thus there are many ways to start the +process. For example, uwsgi version 0.9.6.8 provides a hundred switches. +This guide demonstrates the most important of them, but does not intent to +substitute the official manual and online documentation. + +uWSGI supports configuration through: + +* environment variables +* command line switches +* ldap +* ini files +* xml files +* yaml files + +Managing the uWSGI server +------------------------- + +The system administrator controls the worker process pool by sending signals +to the master process. For example, the unix kill command sends such signals. +uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain +text file containing just a process id. + +Starting the server +------------------- + +Starting an uWSGI server is the role of the system administrator, like +starting the Web server. It is *not* the role of the Web server to start the +uWSGI server. This means: + +* the uWSGI server can be restarted or reloaded independently from the Web + server, +* (except with Cheerokee), it is the role of the system administrator to make + uWSGI to start on boot or reboot: either through tools like supervisor or + daemontools, either directly at init level in a file like /etc/rc.local or + /etc/conf.d/local + +Managing uWSGI +============== + +Starting the server +------------------- + +Example command line for a Web server that understand the uWSGI protocol:: + + uwsgi --chdir=/path/to/your/project + --module='wsgi:application' \ + --env DJANGO_SETTINGS_MODULE=settings \ + --master --pidfile=/tmp/project-master.pid \ + --socket=127.0.0.1:49152 \ # can also be a file + --processes=5 \ # number of worker processes + --uid=1000 --gid=2000 \ # if root, uwsgi can drop privileges + --harakiri=20 \ # respawn processes taking more than 20 seconds + --limit-as=128 \ # limit the project to 128 Megabytes + --max-requests=5000 \ # respawn processes after serving 5000 requests + --vacuum \ # clear environment on exit + --home=/path/to/virtual/env \ # optionnal path to a virtualenv + --daemonize=/var/log/uwsgi/yourproject.log # background the process + +Django specific options are: + +* ``chdir``: should be the path to your project +* ``module``: WSGI module to use, probably the ``wsgi`` module which + :djadmin:`startproject` creates. +* ``pythonpath``: optional path to your project virtualenv +* ``env``: should contain at least ``DJANGO_SETTINGS_MODULE`` + +Example ini configuration file:: + + [uwsgi] + chdir=/path/to/your/project + master=True + pidfile=/tmp/project-master.pid + vacuum=True + max-requests=5000 + deamonize=/var/log/uwsgi/yourproject.log + +Example ini configuration file usage:: + + uwsgi --ini uwsgi.ini + +Read more `uWSGI configuration examples +`_. + +.. admonition:: Massive application hosting + + `uWSGI emperor `_ is a special + uWSGI process that can manage many master processes at once. + +Reloading the daemon +-------------------- + +As mentioned above, the uWSGI master process is one of the core component of +the uWSGI stack. The signal to brutally reload all the workers and the master +process is SIGTERM. Example command to brutally reload the uWSGI processes:: + + kill -TERM `cat /tmp/project-master.pid` + +Patching the daemon +------------------- + +One of the great advantages of uWSGI is its ability to gradually restart each +worker without loosing any request. + +For example, uWSGI can be signaled that worker should reload the code after +handling their current request (if any) from bash:: + + # using kill to send the signal + kill -HUP `cat /tmp/project-master.pid` + + # if uwsgi was started with --touch-reload=/tmp/somefile + touch /tmp/somefile + +Or from Python:: + + uwsgi.reload() + +Stopping the daemon +------------------- + +If you have the process running in the foreground, it's easy enough to stop it: +Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when +you're dealing with background processes, you'll need to resort to the Unix +``kill`` command. + +The ``kill`` is used to send a signal to the uWSGI master process. The +`uWSGI signals are documented online +`_. Example command to +completely stop the uWSGI stack:: + + kill -INT `cat /tmp/project-master.pid` + +HTTP server configuration +========================= + +Nginx setup +----------- + +Nginx provides the `uwsgi module `_ by +default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as +simple as setting it up to proxy requests:: + + location / { + uwsgi_pass 127.0.0.1:49152; + # in case of a socket file: + # uwsgi_pass unix:/tmp/yourproject.sock; + } + +Note that default uwsgi parameters should be included somewhere in your Nginx +configuration. For example:: + + http { + include uwsgi_params; + # [...] normal nginx configuration here + } + +Cherokee setup +-------------- + +Cherokee setup is documented in the `official Cherokee uWSGI documentation +`_. + +Lighttpd setup +-------------- + +`Lighttpd uwsgi module `_ is +still experimental. + +Troubleshooting +=============== + +As usual, the first things to do is to check the logs. This implies: + +* the web server log, which will indicate if it couldn't connect to the uWSGI + process, +* the uWSGI log, which will indicate if an exception was thrown. + +Typical gotchas: + +* If the socket is a file, the Web server process should have read, write and + execute permissions on the socket file. The ``--chmod-socket`` option can do + it. +* In some cases, for instance if uWSGI was started without ``--vacuum`` or + killed with ``SIGKILL``, it won't remove the socket and pidfile when it is + interrupted. It is safe to remove them manually and to start uWSGI again in + that case. +* uWSGI can start the process on the foreground, this will make errors easily + visible to the system administrator. diff --git a/docs/index.txt b/docs/index.txt index 0425da4..f372bc6 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -154,8 +154,8 @@ The development process * **Deployment:** :doc:`Overview ` | - :doc:`Apache/mod_wsgi ` | - :doc:`uWSGI ` | + :doc:`Apache/mod_wsgi ` | + :doc:`uWSGI ` | :doc:`Apache/mod_python (deprecated) ` | :doc:`FastCGI/SCGI/AJP ` | :doc:`Apache authentication ` | diff --git a/docs/ref/contrib/gis/deployment.txt b/docs/ref/contrib/gis/deployment.txt index 14f803d..59003f2 100644 --- a/docs/ref/contrib/gis/deployment.txt +++ b/docs/ref/contrib/gis/deployment.txt @@ -54,7 +54,7 @@ Example:: number of ``processes`` instead. For more information, please consult Django's -:doc:`mod_wsgi documentation `. +:doc:`mod_wsgi documentation `. ``mod_python`` -------------- @@ -62,8 +62,8 @@ For more information, please consult Django's .. warning:: Support for mod_python will be deprecated in a future release of Django. If you are configuring a new deployment, you are strongly encouraged to - consider using :doc:`mod_wsgi ` or any of the - other :doc:`supported backends `. + consider using :doc:`mod_wsgi ` or any of + the other :doc:`supported backends `. Example:: diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index e15fa50..7cbdaf4 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -197,7 +197,7 @@ Methods the ``HTTP_X_FORWARDED_HOST`` (if enabled in the settings) and ``HTTP_HOST`` headers (in that order). If they don't provide a value, the method uses a combination of ``SERVER_NAME`` and ``SERVER_PORT`` as - detailed in :pep:`3333`. + detailed in :pep:`333`. Example: ``"127.0.0.1:8000"`` diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 8c7fe8f..b96fb96 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2095,6 +2095,18 @@ A boolean that specifies whether to use the X-Forwarded-Host header in preference to the Host header. This should only be enabled if a proxy which sets this header is in use. +.. setting:: WSGI_APPLICATION + +WSGI_APPLICATION +---------------- + +.. versionadded:: 1.4 + +Default: ``None`` + +The full Python path of the WSGI application object to use, as created +by :djadmin:`django-admin.py startproject `. + .. setting:: YEAR_MONTH_FORMAT YEAR_MONTH_FORMAT diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index 3229cfd..7121271 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -303,7 +303,7 @@ more flexible ``mod_wsgi`` backend. If you are currently using the ``mod_python`` request handler, you are strongly encouraged to redeploy your Django instances using :doc:`mod_wsgi -`. +`. Function-based generic views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 0130657..3a3c798 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -688,7 +688,7 @@ more flexible ``mod_wsgi`` backend. If you are currently using the ``mod_python`` request handler, you should redeploy your Django projects using another request handler. -:doc:`mod_wsgi ` is the request handler +:doc:`mod_wsgi ` is the request handler recommended by the Django project, but :doc:`FastCGI ` is also supported. Support for ``mod_python`` deployment will be removed in Django 1.5. diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 70b0783..5f3ad52 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -48,7 +48,7 @@ documentation to determine which mode is right for your setup. Make sure you have Apache installed, with the mod_wsgi module activated. Django will work with any version of Apache that supports mod_wsgi. -See :doc:`How to use Django with mod_wsgi ` +See :doc:`How to use Django with mod_wsgi ` for information on how to configure mod_wsgi once you have it installed. @@ -56,7 +56,7 @@ If you can't use mod_wsgi for some reason, fear not: Django supports many other deployment options. One is :doc:`uWSGI `; it works very well with `nginx`_. Another is :doc:`FastCGI `, perfect for using Django with servers other than Apache. Additionally, Django -follows the WSGI spec (:pep:`3333`), which allows it to run on a variety of +follows the WSGI spec (:pep:`333`), which allows it to run on a variety of server platforms. See the `server-arrangements wiki page`_ for specific installation instructions for each platform. diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index 61ddf8c..507b092 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -75,7 +75,7 @@ application what settings file to use. Do that with ``os.environ``:: os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings' Read the :doc:`Django mod_wsgi documentation -` for more information and other common +` for more information and other common elements to a Django WSGI application. Default settings