| 1 |
========================== |
| 2 |
How to deploy static files |
| 3 |
========================== |
| 4 |
|
| 5 |
.. seealso:: |
| 6 |
|
| 7 |
For an introduction to the use of :mod:`django.contrib.staticfiles`, see |
| 8 |
:doc:`/howto/static-files/index`. |
| 9 |
|
| 10 |
.. _staticfiles-production: |
| 11 |
|
| 12 |
Serving static files in production |
| 13 |
================================== |
| 14 |
|
| 15 |
The basic outline of putting static files into production consists of two |
| 16 |
steps: run the :djadmin:`collectstatic` command when static files change, then |
| 17 |
arrange for the collected static files directory (:setting:`STATIC_ROOT`) to be |
| 18 |
moved to the static file server and served. Depending on the ``staticfiles`` |
| 19 |
:setting:`STORAGES` alias, files may need to be moved to a new location |
| 20 |
manually or the :func:`post_process |
| 21 |
<django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method of |
| 22 |
the ``Storage`` class might take care of that. |
| 23 |
|
| 24 |
As with all deployment tasks, the devil's in the details. Every production |
| 25 |
setup will be a bit different, so you'll need to adapt the basic outline to fit |
| 26 |
your needs. Below are a few common patterns that might help. |
| 27 |
|
| 28 |
Serving the site and your static files from the same server |
| 29 |
----------------------------------------------------------- |
| 30 |
|
| 31 |
If you want to serve your static files from the same server that's already |
| 32 |
serving your site, the process may look something like: |
| 33 |
|
| 34 |
* Push your code up to the deployment server. |
| 35 |
* On the server, run :djadmin:`collectstatic` to copy all the static files |
| 36 |
into :setting:`STATIC_ROOT`. |
| 37 |
* Configure your web server to serve the files in :setting:`STATIC_ROOT` |
| 38 |
under the URL :setting:`STATIC_URL`. For example, here's |
| 39 |
:ref:`how to do this with Apache and mod_wsgi <serving-files>`. |
| 40 |
|
| 41 |
You'll probably want to automate this process, especially if you've got |
| 42 |
multiple web servers. |
| 43 |
|
| 44 |
Serving static files from a dedicated server |
| 45 |
-------------------------------------------- |
| 46 |
|
| 47 |
Most larger Django sites use a separate web server -- i.e., one that's not also |
| 48 |
running Django -- for serving static files. This server often runs a different |
| 49 |
type of web server -- faster but less full-featured. Some common choices are: |
| 50 |
|
| 51 |
* Nginx_ |
| 52 |
* A stripped-down version of Apache_ |
| 53 |
|
| 54 |
.. _Nginx: https://nginx.org/en/ |
| 55 |
.. _Apache: https://httpd.apache.org/ |
| 56 |
|
| 57 |
Configuring these servers is out of scope of this document; check each |
| 58 |
server's respective documentation for instructions. |
| 59 |
|
| 60 |
Since your static file server won't be running Django, you'll need to modify |
| 61 |
the deployment strategy to look something like: |
| 62 |
|
| 63 |
* When your static files change, run :djadmin:`collectstatic` locally. |
| 64 |
|
| 65 |
* Push your local :setting:`STATIC_ROOT` up to the static file server into the |
| 66 |
directory that's being served. `rsync <https://rsync.samba.org/>`_ is a |
| 67 |
common choice for this step since it only needs to transfer the bits of |
| 68 |
static files that have changed. |
| 69 |
|
| 70 |
.. _staticfiles-from-cdn: |
| 71 |
|
| 72 |
Serving static files from a cloud service or CDN |
| 73 |
------------------------------------------------ |
| 74 |
|
| 75 |
Another common tactic is to serve static files from a cloud storage provider |
| 76 |
like Amazon's S3 and/or a CDN (content delivery network). This lets you |
| 77 |
ignore the problems of serving static files and can often make for |
| 78 |
faster-loading web pages (especially when using a CDN). |
| 79 |
|
| 80 |
When using these services, the basic workflow would look a bit like the above, |
| 81 |
except that instead of using ``rsync`` to transfer your static files to the |
| 82 |
server you'd need to transfer the static files to the storage provider or CDN. |
| 83 |
|
| 84 |
There's any number of ways you might do this, but if the provider has an API, |
| 85 |
you can use a :doc:`custom file storage backend </howto/custom-file-storage>` |
| 86 |
to integrate the CDN with your Django project. If you've written or are using a |
| 87 |
3rd party custom storage backend, you can tell :djadmin:`collectstatic` to use |
| 88 |
it by setting ``staticfiles`` in :setting:`STORAGES`. |
| 89 |
|
| 90 |
For example, if you've written an S3 storage backend in |
| 91 |
``myproject.storage.S3Storage`` you could use it with:: |
| 92 |
|
| 93 |
STORAGES = { |
| 94 |
# ... |
| 95 |
"staticfiles": {"BACKEND": "myproject.storage.S3Storage"} |
| 96 |
} |
| 97 |
|
| 98 |
Once that's done, all you have to do is run :djadmin:`collectstatic` and your |
| 99 |
static files would be pushed through your storage package up to S3. If you |
| 100 |
later needed to switch to a different storage provider, you may only have to |
| 101 |
change ``staticfiles`` in the :setting:`STORAGES` setting. |
| 102 |
|
| 103 |
For details on how you'd write one of these backends, see |
| 104 |
:doc:`/howto/custom-file-storage`. There are 3rd party apps available that |
| 105 |
provide storage backends for many common file storage APIs. A good starting |
| 106 |
point is the `overview at djangopackages.org |
| 107 |
<https://djangopackages.org/grids/g/storage-backends/>`_. |
| 108 |
|
| 109 |
Learn more |
| 110 |
========== |
| 111 |
|
| 112 |
For complete details on all the settings, commands, template tags, and other |
| 113 |
pieces included in :mod:`django.contrib.staticfiles`, see :doc:`the |
| 114 |
staticfiles reference </ref/contrib/staticfiles>`. |