uWSGI tutorial rewrite #598

Closed
wants to merge 3 commits into
from

Conversation

Projects
None yet
3 participants
@evildmp
Contributor

evildmp commented Dec 18, 2012

First draft of a tutorial for running Django with uWSGI and nginx.

Although this covers nginx specifically, it doesn't exclude other servers (and at least one of the other how-to documents covers Apache in much the same way so I assumed it was OK to be that specific).

The tutorial needs some input from a more expert uWSGI user on configuration options in particular.

@evildmp

This comment has been minimized.

Show comment Hide comment
@evildmp

evildmp Dec 18, 2012

Contributor
@ptone

This comment has been minimized.

Show comment Hide comment
@ptone

ptone Dec 18, 2012

Member

So for some background on this part of the docs see:

https://code.djangoproject.com/ticket/16057
https://code.djangoproject.com/ticket/17073

With the move to making django 1.4 a better WSGI citizen - it should also hold that we shouldn't have to document too much of the non-Django side of each setup.

Meaning we should document where Django has something particular, but allow the server to document how to host WSGI apps and it should "just work" with Django.

That is why in #17073 I contributed content back to the server docs from Django's docs, where they better belong.

If we take on the task of documenting server setup - it just becomes more maintenance burden as servers or their best practices change.

There is also the problem of permutations uWSGI+nginx, uWSGI+apache etc

Django can never document all these configurations, and opinions will vary WIDELY based on preference.

The page is not a tutorial, but notes on what might be specific to Django when running as a WSGI app under uWSGI

I think it could be worth considering a set of deployment cookbook scenarios under a different branch of the docs, with a big disclaimer that there are endless ways to do it, and what are included are just a set of contributed recipes.

Also, for better or worse, Django has not 'enforced' the learning of virtualenv as a pre-requisite for any section of the docs (that I'm aware of), and so shouldn't used in any absolute way - but be pointed out.

So overall, thanks again for a thoughtful take on this topic - my own vote would be to narrow the uWSGI docs down to the minimal steps/reference - retain more of the links to their docs - and then consider keeping something more full fledged like this in a "full recipe" cookbook section with introductory caveat.

Member

ptone commented Dec 18, 2012

So for some background on this part of the docs see:

https://code.djangoproject.com/ticket/16057
https://code.djangoproject.com/ticket/17073

With the move to making django 1.4 a better WSGI citizen - it should also hold that we shouldn't have to document too much of the non-Django side of each setup.

Meaning we should document where Django has something particular, but allow the server to document how to host WSGI apps and it should "just work" with Django.

That is why in #17073 I contributed content back to the server docs from Django's docs, where they better belong.

If we take on the task of documenting server setup - it just becomes more maintenance burden as servers or their best practices change.

There is also the problem of permutations uWSGI+nginx, uWSGI+apache etc

Django can never document all these configurations, and opinions will vary WIDELY based on preference.

The page is not a tutorial, but notes on what might be specific to Django when running as a WSGI app under uWSGI

I think it could be worth considering a set of deployment cookbook scenarios under a different branch of the docs, with a big disclaimer that there are endless ways to do it, and what are included are just a set of contributed recipes.

Also, for better or worse, Django has not 'enforced' the learning of virtualenv as a pre-requisite for any section of the docs (that I'm aware of), and so shouldn't used in any absolute way - but be pointed out.

So overall, thanks again for a thoughtful take on this topic - my own vote would be to narrow the uWSGI docs down to the minimal steps/reference - retain more of the links to their docs - and then consider keeping something more full fledged like this in a "full recipe" cookbook section with introductory caveat.

@evildmp

This comment has been minimized.

Show comment Hide comment
@evildmp

evildmp Dec 19, 2012

Contributor

I do appreciate the point that the Django documentation shouldn't be the place for reference material on other software.

However, I also think that a 'how-to' guide really ought to be something that someone can follow, step-by-step, from a promise to completion.

For someone approaching something like this for the first time, it's important that the process be linear, and avoid choices or branching. Generally speaking, the Django documentation is superb when it comes to reference, but (other than the initial tutorials) has gaps when a beginner is looking for end-to-end walkthroughs.

Would this make more sense as a deployment tutorial perhaps?

Contributor

evildmp commented Dec 19, 2012

I do appreciate the point that the Django documentation shouldn't be the place for reference material on other software.

However, I also think that a 'how-to' guide really ought to be something that someone can follow, step-by-step, from a promise to completion.

For someone approaching something like this for the first time, it's important that the process be linear, and avoid choices or branching. Generally speaking, the Django documentation is superb when it comes to reference, but (other than the initial tutorials) has gaps when a beginner is looking for end-to-end walkthroughs.

Would this make more sense as a deployment tutorial perhaps?

@evildmp

This comment has been minimized.

Show comment Hide comment
@evildmp

evildmp Dec 19, 2012

Contributor

This commit moves the tutorial to docs/howto/deployment/tutorial.txt, and restores docs/howto/deployment/wsgi/uwsgi.txt.

It's now a more general web server deployment tutorial, and makes clear that it offers just one way to set up a web server with Django.

I am not sure where it belongs, whether it should live amongst the deployment documents or whether all tutorials should be collected together.

Contributor

evildmp commented Dec 19, 2012

This commit moves the tutorial to docs/howto/deployment/tutorial.txt, and restores docs/howto/deployment/wsgi/uwsgi.txt.

It's now a more general web server deployment tutorial, and makes clear that it offers just one way to set up a web server with Django.

I am not sure where it belongs, whether it should live amongst the deployment documents or whether all tutorials should be collected together.

@evildmp evildmp referenced this pull request in unbit/uwsgi Jan 2, 2013

Closed

Django/nginx/uwsgi docs #108

@evildmp

This comment has been minimized.

Show comment Hide comment
@evildmp

evildmp Jan 2, 2013

Contributor

The uWSGI committers have adopted this for their docs, so if it's not suitable in its current form for the Django docs I won't be offended if it's not incorporated.

Contributor

evildmp commented Jan 2, 2013

The uWSGI committers have adopted this for their docs, so if it's not suitable in its current form for the Django docs I won't be offended if it's not incorporated.

@timgraham timgraham closed this Jan 15, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment