Document how to deploy multiple sites using the sites framework

[yakoub abaya <sting606@…>]

the SITE_ID configuration is per settings.py .
given the settings.py is unique per django project then this contradicts the whole purpose of sites framework to serve multiple domains using same django project .

i found information elsewhere about defining multiple wsgi.py files for each domain .
meaning in directory where django's default wsgi.py exist should have domain1_wsgi.py and domain2_wsgi.py
and in http server configuration to define parallel wsgi instances per file .

this information looks crucial for sites to actually server its purpose but it is not included in documentation, unless i somehow haven't understood how it is supposed to work .

[Aymeric Augustin]

Generally speaking, the intent is to have two (or more) settings modules with a different value for SITE_ID. You could then use first one on 20 servers and the second one on 10 other servers. This doesn't require a different wsgi module because the wsgi module takes the name of the settings module from the environment.

[yakoub abaya <sting606@…>]

but how is this done ?
how can one project have several independent settings modules ?
this information is crucial and doesn't appear in documentation or provided as a link to other article .
even the comment you wrote is not understood from documentation, so your comment should appear in that documentation .

[Aymeric Augustin]

You create two python modules, like my_project.settings_a and my_project.settings_b, and select the one to use with the DJANGO_SETTINGS_MODULE environment variable, as documented here: ​https://docs.djangoproject.com/en/dev/topics/settings/#designating-the-settings

Apache handles environment variable in a way I'm unable to describe and tends to bite beginners and experienced people alike. That's why the docs suggest selecting the settings to use in the wsgi module when you're using Apache + mod_wsgi : ​https://docs.djangoproject.com/en/dev/topics/settings/#on-the-server-mod-wsgi — but that's really a workaround for a limitation of Apache, you simply set DJANGO_SETTINGS_MODULE on other application servers such as gunicorn or uwsgi.

[yakoub abaya <sting606@…>]

quote "and select the one to use with the DJANGO_SETTINGS_MODULE environment variable"
at what stage and what method should this selection happen ?
should i write middleware that checks response.HOST value and change that parameter accordingly ?

and either case, why isn't this topic covered in documentation ?
for example there is a special section that describes configuring apache wsgi to install django, so why doesn't that section describe how configuration wsgi can allow defining DJANGO_SETTINGS_MODULE parameter (if that is possible ..)

[yakoub abaya <sting606@…>]

i understand now what you mean : ​http://httpd.apache.org/docs/2.4/mod/mod_setenvif.html#setenvif
or better using rewrite rules .

but i suggest this information be added to documentation, referring developers to web server environment variables so they now where to begin .
it is also important to mention the need for multiple settings modules since without them the sites framework won't work .

in fact given that multiple settings modules are required, then this mean the sites framework can only serve a static predetermined domain configuration and do not scale if you intend to implement dynamic domains according to user preferences .

[yakoub abaya <sting606@…>]

or maybe the best way is to inherit from django WSGIHandler and define he environment variable inside CALL method .

[Aymeric Augustin]

Depending on your Apache setup, SetEnvIf may or may not do the right thing. Sorry, this advice is rather unspecific, but you can find all the details in mod_wsgi's documentation.

There's no "best way" in general, it all depends on your setup. However I can guarantee that you can do all you need in your application server's configuration, or at worst in the wsgi module (eg. if you're using Apache + mod_wsgi, rather than gunicorn or uwsgi).

This is seriously turning into a support thread. The docs don't seem that bad to me. Of course, if you don't know what an environment variable is, you need to learn that first, but that's outside the scope of Django. The only concrete improvement I can imagine is to change the title "On the server (mod_wsgi)", because it's only relevant "if you're using mod_wsgi", not "on the server" in general.

[yakoub abaya <sting606@…>]

i still believe that documentation is not sufficient .
i don't expect it to explain what environment variables are, but at least add this line :
"in order to serve multiple domains, then parallel multiple settings modules must be created .
creating multiple settings can be achieved using DJANGO_SETTINGS_MODULE environment variable which is best set using mod_wsgi ."

[Tim Graham <timograham@…>]

In 7b9537fb270e46d9b89ead0c6dc9b9f68dc93131:

Fixed #21567 -- Documented how to deploy multiple sites using the sites framework.

[Tim Graham <timograham@…>]

In 4f0916c374e37ff945f04d7981f3b435eb7cd350:

[1.7.x] Fixed #21567 -- Documented how to deploy multiple sites using the sites framework.

Backport of 7b9537fb27 from master

[Tim Graham <timograham@…>]

In 4db64e8491fb154f65e824b4a0f7d27e66b477cc:

[1.6.x] Fixed #21567 -- Documented how to deploy multiple sites using the sites framework.

Backport of 7b9537fb27 from master