Improve FastCGI documentation

[minasmorath]

Background

I have been attempting to install Django using lighttpd and FastCGI on a personal Arch Linux server for about 3-7 hours a day, for a week straight. I still don't have all the kinks worked out, and there is quite literally zero useful documentation anywhere, including within the documentation in this page.

Problem

The Documentation on the use of FastCGI is terribly lacking, as well as the documentation on it's use with lighttpd to serve Django applications. There are files (specifically the 'mysite.fcgi' file) that are only mentioned in passing when they are actually the key to getting the system up and running, and their contents is never even dabble in, let alone suffiiently explained. Many config options and directories are given as examples and have no obvious correlation to anything relevant, and their repeated use does not clear up any of the issues supposedly addressed.

Solution

Every section that mentions lighttpd and FastCGI needs to be heavily edited or completely rewritten, some extra content that absolutely needs to be added can be found *cannot include thanks to the spam filter*, such as the coverage of the elusive 'mysite.fcgi' file, and some extra effort needs to be made in the area of descriptive naming conventions.

mysite.fcgi

Some content overview (or any mention of its existance whatsoever) would save many many hours of valuable time and many dollars of resources. A basic config I have happend upon is as such:

#!/usr/bin/python 
import sys, os 

# Add a custom Python path. 
sys.path.insert(0, "/home/jdoe/django-projects") 

# Switch to the directory of your project. (Optional.) 
# os.chdir("/home/jdoe/django-projects/blog") 

# Set the DJANGO_SETTINGS_MODULE environment variable. 
os.environ['DJANGO_SETTINGS_MODULE'] = "blog.settings" 

from django.core.servers.fastcgi import runfastcgi 
runfastcgi(method="threaded", daemonize="false")

Concerning Pathname Conventions

Pathnames are a constant confusion point in this particular doc, what is the /media/ direcory even used for, why is it pointing to some arbitrary path in a users home directory? What is the 'favicon.ico' even used for and why the devil is it included in a server config file?

Conclusion

My point is this: Considering the great lack of documentation in the entire open source realm, it would be a great step forward if one of the larger projects of that realm made headway in documentation quality. Django is a widely used tool in rapid website development, but much more documentation is needed to assist the newest of users.

[Russell Keith-Magee]

Edited ticket subject to avoid pointless hyperbole.

@minasmorath: I was strongly tempted to close the ticket as a lesson in not blowing issues out of proportion. If printed, Django's documentation runs to almost 900 pages. Claiming that Django's documentation is universally poor is patently false, and claiming that we should "make headway in documentation quality" without actually offering to help isn't a great way to make friends.

The documentation of FastCGI may benefit from improvements, but FastCGI is one very small part of Django as a whole - and, I would add, is not the recommended deployment scheme for Django newcomers - ​a fact that is itself documented.

In short - patches welcome. Hyperbole not so welcome.

[Gabriel Hurley]

There is no patch here... how can it need improvement? ;-)

I'm going to look at all the lighttpd/fcgi docs tickets soon, so I'll take this one under advisement as well.

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[Tim Graham]

FastCGI is being deprecated.