uWSGI documentation

[James Pic]

Hello everybody,

Do you think uWSGI deserves a place in the official django documentation ?

I think it should because it's easier, safer, faster and more secure
than flup or mod_wsgi. Also, it made my sysadmin life really easy and
that's something cool to share with the community.

In this case, please consider the attached draft
(django/docs/howto/deployment/uwsgi.txt): it's not perfect and
probably not commitable as-is, but I am ready to listen to feedback
and improve it. Otherwise it'll just make another blog post.

What do you think ?

Cheers

[Łukasz Rekucki]

+1. More docs didn't hurt anybody. At least while there is someone to
maintain them.

>
> What do you think ?
>

My first impression is that you're focusing too much on all those
switches. That section got me totally lost. That should be simplified.
Also, do I really need to type all that stuff? I probably won't be
doing that on production, so showing how to place it in a
configuration file would be better.

I would also drop the whole "advantages" section. The purpose of the
page is to show how to deploy a Django app on uWSGI, not compare it
against other solutions. You also mention some features, but never
show how to enable/use them which is confusing.

PS. Do you think having a `runuwsgi` command similar to `runfcgi`
would be useful ?

--
Łukasz Rekucki

[Roberto De Ioris]

I have made a tiny runuwsgi implementation:

http://projects.unbit.it/uwsgi/browser/contrib/runuwsgi.py

it tries to autoload plugins and spawn the embedded http router/proxy on a default port.

You can specify the socket=ADDR option to disable the http part and bind the server on a uwsgi socket (for directly pointing your webserver to it)

It run multithreaded (8 threads) but i suppose that this could be another configurable option.

It requires a 0.9.7.2 uWSGI version (released in a couple of days) or the current mercurial tip.

I hope it can be useful

--
Roberto De Ioris
http://unbit.it

[Florian Apolloner]

On Apr 2, 1:23 pm, James Pic <james...@gmail.com> wrote:
> I think it should because it's easier, safer, faster and more secure
> than flup or mod_wsgi. Also, it made my sysadmin life really easy and
> that's something cool to share with the community.

+1 on more docs, since uwsgi is quite useable by now. But please leave
claims like faster etc out if you can't back it up. Especially since
david cramer showed on pycon that it makes no difference for them and
both are equal... (and yes I do consider disqus as a relevant
benchmar ;))

Cheers, florian

[Kristaps Kūlis]

Hi,
How uwsgi is more secure than FastCGI ?
I believe that running manage.py for production deployments is "not
way to go", as it has been noted by django devs previously.
What purpose would runuwsgi command serve ?

> --
> You received this message because you are subscribed to the Google Groups "Django developers" group.
> To post to this group, send email to django-d...@googlegroups.com.
> To unsubscribe from this group, send email to django-develop...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
>
>

[Roberto De Ioris]

> Hi,
> How uwsgi is more secure than FastCGI ?

I think he is referring to the various included jailing systems (chroot,
linux namespaces, posix capabilities...) because if we are talking about
protocols there are no really differences between uwsgi and FastCGI, both
are unsecure by-design :)

> I believe that running manage.py for production deployments is "not
> way to go", as it has been noted by django devs previously.
> What purpose would runuwsgi command serve ?

I see it as a way to easily use the embedded uwsgi module/api before going
into production. If a user want to use something like the uWSGI timer/cron
system

http://projects.unbit.it/uwsgi/wiki/DjangoTimers
http://projects.unbit.it/uwsgi/wiki/CronInterface

it can just start coding without passing for all the stack configuration.

[is_null]

On Apr 4, 3:59 pm, Kristaps Kūlis <kristaps.ku...@gmail.com> wrote:
> I believe that running manage.py for production deployments is "not
> way to go", as it has been noted by django devs previously.
> What purpose would runuwsgi command serve ?

I'm unsure. Roberto's proposal is interresting: i could configure
uwsgi in settings.py and then just run runuwsgi. Although that looks a
little to much for django itself, it would be great in a pluggable
django app.

That said i'd love to *not* have to put a 3 liners module in my
project directory anymore. A runuwsgi command might not be the only
way to solve this need.

On Apr 2, 4:44 pm, Łukasz Rekucki <lreku...@gmail.com> wrote:
>
> +1. More docs didn't hurt anybody. At least while there is someone to
> maintain them.
>

You can count on me (until death).

>
> > What do you think ?
>

> My first impression is that you're focusing too much on all those
> switches. That section got me totally lost. That should be simplified.
> Also, do I really need to type all that stuff? I probably won't be
> doing that on production, so showing how to place it in a
> configuration file would be better.
>
> I would also drop the whole "advantages" section. The purpose of the

> page is to show how to deploy a Django app onuWSGI, not compare it

> against other solutions. You also mention some features, but never
> show how to enable/use them which is confusing.

Thanks for your feedback, I did my best to take it in consideration
while rewriting most of the documentation this week.

(Some examples are still missing but most of it is there. Feedback is
always appreciated)

============================
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.

.. _uWSGI: http://projects.unbit.it/uwsgi/

Prerequisite: uWSGI
===================

`uWSGI wiki<http://projects.unbit.it/uwsgi/wiki/Install>`_ 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

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 (>1024) local
port like
127.0.0.1:3000. 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:

* command line switches
* ini files
* xml 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,
* 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
==============

Configuring the project
-----------------------

Starting a process with uWSGI takes an additional python script. The
script
can be in the project directory, named 'youruwsgi.py'::

from django.core.handlers.wsgi import WSGIHandler

# set application for WSGI processing
application = WSGIHandler()

Starting the server
-------------------

Example command line for a Web server that understand the uWSGI_
protocol::

uwsgi --home=/path/to/your/project --module=youruwsgi \
--master --pidfile=/tmp/project-master.pid \
--socket=127.0.0.1:3000 \ # 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
--daemonize=/var/log/uwsgi/yourproject.log # background the
process

Django specific options are:

* home: should be the path to your project
* module: should be the name of your uwsgi module, ie. youruwsgi
* pythonpath: optionnal path to your project virtualenv

Example ini configuration::

Example ini configuration usage::

Example xml configuration::

Example xml configuration usage::

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)::

kill -HUP `cat /tmp/project-master.pid`

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
<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. 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 these days. Configuring
Nginx to
use an uWSGI server is as simple as setting it up to proxy requests::

location / {
uwsgi_pass 127.0.0.1:3000;
# 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
--------------

Lighttpd setup
--------------

Apache setup
------------

Troubbleshoting
===============

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

Tipical gotchas:

* if the socket is a file: the Web server process should have read,
write and
execute permissions on the socket file
* uWSGI_ 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

[Mikhail Korobov]

Hi James,

Some notes:

> One of the great advantages of uWSGI_ is its ability to gradually
> restart each worker without loosing any request.

I think mod_wsgi in daemon mode is doing the same.

> Nginx provides the uwsgi module by default these days.

Stock nginx does not provide uwsgi module on latest CentOS, RedHat,
Debian and even on latest released Ubuntu by default. Ubuntu will
update default nginx to 0.8.x soon but on other OS'es 0.7.x or even
0.6.x will remain default for a long time.

> location / {
> uwsgi_pass 127.0.0.1:3000;
> # in case of a socket file:
> # uwsgi_pass unix:/tmp/yourproject.sock;
> }

According to this: http://www.iana.org/assignments/port-numbers 3000
port "SHOULD NOT be used without IANA registration. The registration
procedure is defined in [RFC4340], Section 19.9." because it is one of
"DCCP Registered ports". I don't know if this is a serious issue but
it seems that it is better to recommend port numbers above 49152 in
tutorials.

Thanks!

>     pip installhttp://projects.unbit.it/downloads/uwsgi-lts.tar.gz

[Roberto De Ioris]

> That said i'd love to *not* have to put a 3 liners module in my
> project directory anymore. A runuwsgi command might not be the only
> way to solve this need.
>

Remember that you do not need those file anymore:

[uwsgi]
env = DJANGO_SETTING_MODULE=mysite.settings
chdir = <django_app_directory>
module = django.core.handlers.wsgi:WSGIHandler()
...
...

Or you can do magic with placeholder like this:

[uwsgi]
my_django_app = mysite
env = DJANGO_SETTING_MODULE=%(my_django_app).settings
chdir = /apps/%(my_django_app)
module = django.core.handlers.wsgi:WSGIHandler()

(obviously this rules apply to xml,yaml,ldap,command line and so on...)

> uWSGI_ supports configuration through:
>
> * command line switches
> * ini files
> * xml files

yaml is supported too and you should mention environment variables, they are
used a lot on already available *BSD init scripts

Probably i would add a section about massive hosting of applications using
the Emperor (The Emperor doc is probably the only good one of all the
uWSGI project as it is not written by me :) )

http://projects.unbit.it/uwsgi/wiki/Emperor

One of the most-loved (by me too) feature of mod_wsgi is its
virtualhosting capability
tied-in with apache. uWSGI in the past forced you to manually manage a
instance for every app or use the PITA (but funny and hacky)
multiple-interpreters-way. The Emperor solves this problem elegantly and
with a lot of attention about clouding/hosting platforms.

>
> 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,
> * 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

Nothing to say against this, but Cherokee (as an example) manages the
uWSGI processes itself (it is an exception to the rule, i do not know if
it is worth mentioning it).

>
> 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)::
>
> kill -HUP `cat /tmp/project-master.pid`

You can gracefully reload (in 0.9.7 tree) simply touching a file with
the --touch-reload = <file> option and (probably more important) you can
reload from the app itself using uwsgi.reload()

>
>
> Tipical gotchas:
>
> * if the socket is a file: the Web server process should have read,
> write and
> execute permissions on the socket file

you should mention the --chmod-socket option here

> * uWSGI_ won't remove the socket and pidfile when it is interrupted,

here --vacuum option should be reported, but i will put enphasis on the
inhability to remove socket/pidfile if you "kill -9" the uWSGI stack

If you have some doubt please ask me or the official uWSGI mailing-list i
know that uWSGI official docs are really bad and not synced with the
current code :P

[Graham Dumpleton]

To be blunt, you are actually asking a lot for them to host detailed documentation on uWSGI integration on the Django site for every possible way it can be setup. I haven't even managed to get much more than minimal setup instructions for mod_wsgi into the official Django documentation.

I believe you will find that they don't really believe it is for them to be providing extensive documentation on particular hosting mechanisms, or at least they don't have the time. Personally I do find that stance a bit odd as they should be striving to at least ensure that it is as painless as possible for users to get it going on at least the mainstream hosting methods to combat the accusations that it is too hard. As such, the minimal documentation they provide at the moment is quite often not enough.

To me this should extend to ensuring that interfaces in the framework make it easy and predictable. It is a said state of affairs though that pretty well all the Python web frameworks give minimal time to ensuring that the experience of a user as far as hosting it is as simple as possible and why every framework is so different and don't use some sort of common defining mechanism for an entry point.

I would thus perhaps suggest you instead provide just the most common configuration which will work for most users and would be easiest and then have a link back to any more detailed documentation on your own site relevant specifically to Django, as well as link to more general purpose documentation on your own site. It would then be the documentation on your site which describes all the variations.

If you really want to attract Django users, you might also consider what I have had on my TODO list for quite a while, but haven't had time to do (but might this year), which is to write a distinct comprehensive self contained tutorial on how to setup your WSGI hosting mechanism with Django. This can't though just concentrate on the specifics of your hosting mechanism, but because newbies are sometimes quite inexperienced, touch on issues of user rights, file system permissions, where stuff should be installed and general security concerns, plus how to manage updates of Django and application code etc etc. Yes, it is a lot of work, but if you really want to try and attract users of a specific framework to you, you need to do it eventually.

Graham

[Russell Keith-Magee]

On Sat, Apr 9, 2011 at 2:15 PM, Graham Dumpleton
<graham.d...@gmail.com> wrote:
> To be blunt, you are actually asking a lot for them to host detailed
> documentation on uWSGI integration on the Django site for every possible way
> it can be setup. I haven't even managed to get much more than minimal setup
> instructions for mod_wsgi into the official Django documentation.
> I believe you will find that they don't really believe it is for them to be
> providing extensive documentation on particular hosting mechanisms, or at
> least they don't have the time. Personally I do find that stance a bit odd
> as they should be striving to at least ensure that it is as painless as
> possible for users to get it going on at least the mainstream hosting
> methods to combat the accusations that it is too hard. As such, the minimal
> documentation they provide at the moment is quite often not enough.

I'm a little confused by this sentiment. Why is it Django's role to
provide full documentation for mod_wsgi (or any other deployment
interface, for that matter)? If people are complaining that mod_wsgi
is too hard to use, why is that a failure of *Django's* documentation?

Django isn't the sole arbiter of all documentation. We are in a
position to document Django. We are in a position to point out the
unique requirements that Django may have (for example, what needs to
be in the system path and environment). We can -- and do -- link to
the official documentation for mod_wsgi.

At some point, the issue with deploying Django under X has less to do
with Django, and more to do with the eccentricities of X. That's the
point at which, IMHO, it ceases to be Django's responsibility to
provide documentation. I don't think it's Django's place to document
mod_wsgi any more than it's Django's place to document MySQL or
SQLite. We provide the detail to explain the Django-specific friction
points that exist, but beyond that, it's up to those external (to
Django) libraries to provide adequate documentation for their own
configurations.

> To me this should extend to ensuring that interfaces in the framework make
> it easy and predictable. It is a said state of affairs though that pretty
> well all the Python web frameworks give minimal time to ensuring that the
> experience of a user as far as hosting it is as simple as possible and why
> every framework is so different and don't use some sort of common defining
> mechanism for an entry point.

Again, I'm confused here -- to my reading, this "common defining
mechanism" is what WSGI is supposed to be.

You won't get any argument out of me that Django has some quirks that
makes deployment harder than it should be -- for example, the path
munging problems that you've blogged about in the past. You won't get
any argument out of me that these issues should be addressed.

The reason we spend "minimal time" addressing these problems is that
in the grand scheme of things, deployment pain is quite far down the
list of problems that we have. Yes, Django has deployment quirks. Yes,
this makes it harder for absolute beginners to get started. However,
once you understand those quirks (as any non-beginning Django user
must do), deployment simply isn't that big a problem.

I completely agree that deploying Django could be *better*, but like
it or not, the status quo *works*, and the 'itch' that would cause
someone to address this issue is a relatively minor annoyance. On the
other hand, issues like logging, handling of static files, controlling
cascading behavior during deletion, i18n and l10n are problems that
are real, current, and affect *every* Django user, be they novice or
master. The incentive to work on these issues (and I've just picked
the ones we addressed in 1.3) is much higher.

If someone wants to take a swing at addressing these Django-specific
deployment issues, I fully support that. However, that doesn't just
mean pointing out the problems that exist -- we already know they
exist. It means providing a concrete patch that fixes those problems,
or at least can be used as a starting point for further discussion.

Yours,
Russ Magee %-)

[Roberto De Ioris]

> To be blunt, you are actually asking a lot for them to host detailed
> documentation on uWSGI integration on the Django site for every possible
> way
> it can be setup. I haven't even managed to get much more than minimal
> setup
> instructions for mod_wsgi into the official Django documentation.
>
>

I have asked anything, other users spawned this thread, and as the main
uWSGI author i am doing suggestions/corrections.

[Graham Dumpleton]

On Saturday, April 9, 2011 5:35:14 PM UTC+10, Russell Keith-Magee wrote:

On Sat, Apr 9, 2011 at 2:15 PM, Graham Dumpleton
<graham.d...@gmail.com> wrote:
> To be blunt, you are actually asking a lot for them to host detailed
> documentation on uWSGI integration on the Django site for every possible way
> it can be setup. I haven't even managed to get much more than minimal setup
> instructions for mod_wsgi into the official Django documentation.
> I believe you will find that they don't really believe it is for them to be
> providing extensive documentation on particular hosting mechanisms, or at
> least they don't have the time. Personally I do find that stance a bit odd
> as they should be striving to at least ensure that it is as painless as
> possible for users to get it going on at least the mainstream hosting
> methods to combat the accusations that it is too hard. As such, the minimal
> documentation they provide at the moment is quite often not enough.

I'm a little confused by this sentiment. Why is it Django's role to
provide full documentation for mod_wsgi (or any other deployment
interface, for that matter)?

I am not saying it is and why I was stating that for uWSGI at most what they should be hoping for is to get the most minimal documentation included. I believe that they might have been going over the top in the expectations of what could be included when I started seeing some of the stuff posted especially since they were things that weren't even unique to using Django with uWSGI.

If people are complaining that mod_wsgi
is too hard to use, why is that a failure of *Django's* documentation?

I didn't specifically say that mod_wsgi in particular is too hard, it was a general statement about use of Django with any hosting mechanism. Django prides itself on having really excellent documentation but experience has shown that in the area of hosting, what documentation you provide keeps falling a bit short because of the constant questions about the issues. You even mention some of the pain points below around sys.path. Another is static media host, the differences between media and static area etc. There is also the SCRIPT_NAME issue with LOGIN_URL and LOGOUT_URL These are peculiarities to Django. If I were to remove tomorrow the Django specific integration notes from the mod_wsgi site and you didn't yourselves document these Django specific issues, then what are your users going to do. I though would be able to quite rightly say, 'well how to use mod_wsgi is documented over there, if you can't work out how to make a specific framework work because the framework doesn't explain then it isn't my problem'.

In fact I have actually taken this specific stance with most of the other Python web frameworks and removed the documentation from the mod_wsgi site about them. This was in part done because some changed how to work with the frameworks between versions and it was too much to keep track of it and they couldn't be bothered to highlight the differences. It has also been because they had certain things that had to be done in certain ways with anything but their own included server and they weren't documenting it. Given that they didn't seem interested in devoting much time to the area of hosting and regarded documenting how to do it properly as not their problem, even for those things which were specific to their framework I just gave up and left it up to them. Faced with that they have started to improve the documentation but across the board the problem is still one of frameworks providing a simple example but not really going in depth into why things are done certain ways so that when things go wrong for a user that they have some clue as to why. As such, you never get rid of the questions from people about why things don't work when their setup isn't exactly as per the prototypical setup.

Even though I don't use Django myself I have always paid a great deal of attention to what problems people were having and would answer questions on the Django forums, StackOverflow and mod_wsgi list even though a lot of the time they related to the Django specific issues and nothing to do with mod_wsgi itself. I would update my own Django integration documentation at least to address these issues. When I have tried to highlight problems that the Django documentation didn't perhaps explain well enough, such as sys.path and need for parent and site directories, the response has been one of 'I don't see a problem' from the list. Still though people get confused by the documentation. So, may not be confusing to an experienced user, but the newbies don't understand and that seems to be missed.

So, that is my gripe, that the documentation in place isn't a bit more friendly to newbies who don't have the experience of those people who think there is no problem with the documentation. And yes I have raised these issues on the list a number of times and have blogged about issues to highlight some of them. Of course people will say as they always do in the Open Source would that I should go and fix it myself. Frankly, considering that I don't even use Django I have already done much more than what any sane person would do when I don't even have a reason for doing it, this argument doesn't go very far with me, especially when people don't even want to accept that there is a problem to be fixed and believe the issues are trivial.

> To me this should extend to ensuring that interfaces in the framework make

> it easy and predictable. It is a said state of affairs though that pretty
> well all the Python web frameworks give minimal time to ensuring that the
> experience of a user as far as hosting it is as simple as possible and why
> every framework is so different and don't use some sort of common defining
> mechanism for an entry point.

Again, I'm confused here -- to my reading, this "common defining
mechanism" is what WSGI is supposed to be.

WSGI only describes the API, it doesn't describe a uniform way of deploying it across different hosting mechanisms. Thus ever framework exposes it in different ways, plus each hosting mechanism has different requirements of how to hook into it as well. Things could be much better and simpler if some uniformity were introduced to the area of deployment itself. So, I am not talking about WSGI itself but the bits around that.

Anyway, as you can see the above is a pain point for me as it has been for some time. Probably because I see a lot more of the problems people are having with Django deployment than you do and that I am fool enough to try and help them. Before I get myself even more worked up over this issue I think it best I just take my ball and go. I will not go all spiteful and remove the Django integration notes from the mod_wsgi site, but I will step back from answering Django questions for the time being and cool off.

Graham

[Russell Keith-Magee]

On Sat, Apr 9, 2011 at 4:42 PM, Graham Dumpleton

Graham -- I've been singularly impressed by the way you offer to help
out people with their Django deployment problems, even when they seem
to afflicted with a clinically inability to read instructions or take
a systematic approach to solving problems. I don't know if you've got
the impression that your efforts aren't appreciated -- from me, at
least, they most certainly are, and I'm sure the rest of the core team
would join me in that sentiment. Thank you for everything you have
done in this regard.

We've also clearly been spoiled by the existence of mod_wsgi's docs.
To be completely honest, I hadn't even looked at Django's mod_wsgi
docs for some time, and I was quite surprised at how terse they were
when I actually went and took a look. I completely agree that there is
room for improvement here. When it comes to documentation, there
always is; but in this case, I'd argue we're at the bare minimum
acceptable level right now. We've obviously been leaning on the "see
the mod_wsgi docs" link for far too long.

As for your pain points, and Django rejecting your suggestions -- all
I can say is that there is a very important difference between:

a) We haven't implemented your change,
b) We agree the problem you describe exists, but not on the solution
you propose,
c) We have rejected your change.
d) We aren't aware that you think a change needs to be made

Problems like sys.path munging fall into category (a). I completely
agree that this *is* a problem. I completely agree that it *should* be
fixed. The only issue is resourcing and prioritization. Unfortunately,
fixing this particular problem is worse than trying to untangle
Christmas tree lights, and because there's a fully functional
workaround (a.k.a. "learn how it works from your first experience"),
we haven't got people clamoring to fix the issue.

The handling of LOGIN_URL/SCRIPT_PREFIX is an example of category (b),
The last time this came up [1] it was in response to feedback that
Jacob had given, and while I backed Jacob's decision, I agreed that
something needed to be done as a documentation task. There was also an
ongoing discussion that suggested some alternate approaches to the
problem. However, this discussion never went anywhere -- it never
resulted in a patch, or even a ticket for the required documentation
issue. As a result, a problem that starting in category (b) ended up
in category (a) due to a lack of driving attention -- it just fell
through the cracks.

From a quick survey of your involvement on django-dev for the last
year or so, I can't find any examples of category (c). If I'm wrong on
this, please let me know.

That leaves us with (d). Your involvement helping debug the world's
WSGI problems does put you in an almost unique position to point out
the specific problems with Django's documentation, especially with
newcomers. However, I could only find 1 ticket in Django's tracker
that you've opened yourself [2] -- #11229, which was closed (with the
requested change to documentation being made) within 2 months of being
opened. If we're not implementing the changes you think need to be
made, I put it to you that one of the reasons is that we're simply not
aware of the changes you think need to be made.

Now, this may be because the baseline document is so woeful, and
making specific suggestions on a document that is bad to start with
doesn't serve much purpose. So, let me propose a course of action to
remedy this.

If you would rather that Django takes over management of the "Django
under mod_wsgi" document that is currently hosted on mod_wsgi's site,
I will commit to getting a version of that document integrated into
Django's documentation as an updated version of our mod_wsgi
documentation. Let me know if you want to do this, and I'll open a
ticket and make it happen.

Beyond that, if you have specific suggestions for how Django's
documentation should be improved, I can only ask that you open a
ticket. If you provide draft updates as a patch, that will help
lubricate the process, but even if you don't -- tickets are the only
reliable way we have for getting suggestions integrated into Django.

Once again -- thanks for all the work you've done, both on mod_wsgi in
general, and in supporting Django users using mod_wsgi. It's most
certainly appreciated. Even though you're not part of the Django core
team, your work is a vital part of the Django ecosystem (not to
mention the broader Python web ecosystem); I don't want to alienate
someone who plays such an important part of Django's continued
success.

[1] http://groups.google.com/group/django-developers/browse_thread/thread/fa3661888716f940
[2] http://code.djangoproject.com/query?status=assigned&status=closed&status=new&status=reopened&reporter=grahamd

Yours,
Russ Magee %-)

[is_null]

Thanks a lot Roberto and Mikhail for your feedback.

This update includes the changes you requested, as well as more links
to uWSGI wiki: http://piratepad.net/DISxvZLCdG

Is there any other action to take ?

[Roberto De Ioris]

Seems very good to me, the only thing that i would really change is --home
to --chdir
as --home is used for virtualenv. In my experience using --chdir with django
causes less headache to users.

Probaly you could add the same example written with a ini file too, only
to show users that they not need to write such huge command lines :)

Another (maybe important) note to add is that uWSGI does not run on Windows

[is_null]

Thanks Roberto for your feedback.

The text seems ready so i created a ticket:

http://code.djangoproject.com/ticket/16057

Again, any positive feedback and/or violent flames are welcome.

James