1
0
mirror of https://github.com/django/django.git synced 2024-12-23 01:25:58 +00:00

Docs: Updated content of "sites" framework page.

This commit is contained in:
sdarwin 2024-03-14 10:32:01 -06:00
parent 175b04942a
commit 38aa99ce1b

View File

@ -36,7 +36,19 @@ try to get the current site by comparing the
:attr:`~django.contrib.sites.models.Site.domain` with the host name from
the :meth:`request.get_host() <django.http.HttpRequest.get_host>` method.
How you use this is up to you, but Django uses it in a couple of ways
Historically, the original implementation of "sites" required adding a SITE_ID
in the settings file. This method implied that you would be running multiple
application/web instances, each with a potentially different :setting:`SITE_ID`.
Even today, if you opt to specify the :setting:`SITE_ID` in the settings file,
it will require multiple app/web deployments (to support multiple
``SITE_IDs``). The newer
:func:`~django.contrib.sites.shortcuts.get_current_site` function, by comparing
the domain in every request, enables the ability to serve multiple sites from
one app instance. To take advantage of this modernized design, omit
:setting:`SITE_ID` from your settings file and use
``get_current_site(request)``.
How you use "sites" is up to you, but Django uses it in a couple of ways
automatically via a couple of conventions.
Example usage
@ -269,12 +281,15 @@ To enable the sites framework, follow these steps:
#. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting.
#. Define a :setting:`SITE_ID` setting::
#. Define a :setting:`SITE_ID` setting.\*::
SITE_ID = 1
#. Run :djadmin:`migrate`.
\*Although not in every case. See "Installation Scenarios" in the next
section.
``django.contrib.sites`` registers a
:data:`~django.db.models.signals.post_migrate` signal handler which creates a
default site named ``example.com`` with the domain ``example.com``. This site
@ -282,10 +297,37 @@ will also be created after Django creates the test database. To set the
correct name and domain for your project, you can use a :ref:`data migration
<data-migrations>`.
In order to serve different sites in production, you'd create a separate
settings file with each ``SITE_ID`` (perhaps importing from a common settings
file to avoid duplicating shared settings) and then specify the appropriate
:envvar:`DJANGO_SETTINGS_MODULE` for each site.
In order to serve different sites in production, one option is to create a
separate settings file with each ``SITE_ID`` (perhaps importing from a common
settings file to avoid duplicating shared settings) and then specify the
appropriate :envvar:`DJANGO_SETTINGS_MODULE` for each site.
Installation Scenarios
============================
Scenario 1. As discussed below in "How Django uses the sites framework",
enabling the framework is strongly encouraged because Django takes advantage
of it in a few places. Frequently a Django installation is powering only a
single site. For those cases, define a :setting:`SITE_ID` setting::
SITE_ID = 1
Scenario 2. When planning to leverage the sites framework the way it is
intended (with multiple domains) you may still set the :setting:`SITE_ID`
as before, but since there can only be one :setting:`SITE_ID` in the
settings file it requires launching multiple instances of your app, which
increases the complexity of deployments. To be able to host multiple domains
simultaneously without multiple deployments, it is advantageous to omit the
:setting:`SITE_ID` setting, and use ``get_current_site(request)``. The
absence of a :setting:`SITE_ID` variable may create difficulties in local
development environments, and CI tests, both of which depend on "sites" being
functional. Consider defining settings this way::
if CI or LOCAL_DEVELOPMENT:
SITE_ID = 1
(Be sure to assign a value to either CI or LOCAL_DEVELOPMENT, in those
environments.)
Caching the current ``Site`` object
===================================
@ -507,6 +549,10 @@ Finally, to avoid repetitive fallback code, the framework provides a
:meth:`request.get_host() <django.http.HttpRequest.get_host>` if the
:setting:`SITE_ID` setting is not defined.
If :setting:`SITE_ID` is defined, it takes precedence. Therefore, to
utilize the full capabilities of ``get_current_site(request)`` to
process a ``request``, remove :setting:`SITE_ID` from settings.
Both a domain and a port may be returned by :meth:`request.get_host()
<django.http.HttpRequest.get_host>` when the Host header has a port
explicitly specified, e.g. ``example.com:80``. In such cases, if the