Rewritten managing static files howto. Fixes #19897 . #801

Closed
wants to merge 5 commits into
from

4 participants

@reinout

Splitted out a second howto for using static files in production.

Fixed a couple of references to/from other files.

@wimfeijen wimfeijen Rewritten managing static files howto.
Splitted out a second howto for using static files in production.

Fixed a couple of references to/from other files.
a0ae4c0
@ptone ptone and 1 other commented on an outdated diff Feb 24, 2013
docs/howto/static-files-in-production.txt
+of the Storage takes care of that.
+
+Of course, as with all deployment tasks, the devil's in the details. Every
+production setup will be a bit different, so you'll need to adapt the basic
+outline to fit your needs. Below are a few common patterns that might help.
+
+Serving the app and your static files from the same server
+----------------------------------------------------------
+
+If you want to serve your static files from the same server that's already
+serving your site, the basic outline gets modified to look something like:
+
+* Push your code up to the deployment server.
+* On the server, run :djadmin:`collectstatic` to copy all the static files
+ into :setting:`STATIC_ROOT`.
+* Point your web server at :setting:`STATIC_ROOT`. For example, here's
@ptone
Django member
ptone added a line comment Feb 24, 2013

maybe instead "Configure your web server to point to" Point in this usage isn't as clear as configure

@reinout
reinout added a line comment Feb 24, 2013

Good point; fixing it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ptone ptone and 1 other commented on an outdated diff Feb 24, 2013
docs/howto/static-files-in-production.txt
+ from fabric.api import *
+
+ # Hosts to deploy onto
+ env.hosts = ['www1.example.com', 'www2.example.com']
+
+ # Where your project code lives on the server
+ env.project_root = '/home/www/myproject'
+
+ def deploy_static():
+ with cd(env.project_root):
+ run('./manage.py collectstatic -v0 --noinput')
+
+Serving static files from a dedicated server
+--------------------------------------------
+
+Most larger Django apps use a separate Web server -- i.e., one that's not also
@ptone
Django member
ptone added a line comment Feb 24, 2013

confusing use of "apps" here, instead "Django projects" won't confuse

@reinout
reinout added a line comment Feb 24, 2013

I talked with Aymeric shortly and "site" fits better here than "project".
"App" will have to go, though :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ptone ptone and 1 other commented on an outdated diff Feb 24, 2013
docs/howto/static-files-in-production.txt
+ # Hosts to deploy onto
+ env.hosts = ['www1.example.com', 'www2.example.com']
+
+ # Where your project code lives on the server
+ env.project_root = '/home/www/myproject'
+
+ def deploy_static():
+ with cd(env.project_root):
+ run('./manage.py collectstatic -v0 --noinput')
+
+Serving static files from a dedicated server
+--------------------------------------------
+
+Most larger Django apps use a separate Web server -- i.e., one that's not also
+running Django -- for serving static files. This server often runs a different
+type of web server -- faster but less full-featured. Some good choices are:
@ptone
Django member
ptone added a line comment Feb 24, 2013

we have to be very careful about value judgements on other tools - maybe s/good/common?

@reinout
reinout added a line comment Feb 24, 2013

Done

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ptone ptone and 1 other commented on an outdated diff Feb 24, 2013
docs/howto/static-files-in-production.txt
+For example, if you've written an S3 storage backend in
+``myproject.storage.S3Storage`` you could use it with::
+
+ STATICFILES_STORAGE = 'myproject.storage.S3Storage'
+
+Once that's done, all you have to do is run :djadmin:`collectstatic` and your
+static files would be pushed through your storage package up to S3. If you
+later needed to switch to a different storage provider, it could be as simple
+as changing your :setting:`STATICFILES_STORAGE` setting.
+
+For details on how you'd write one of these backends,
+:doc:`/howto/custom-file-storage`.
+
+.. seealso::
+
+ The `django-storages`__ project is a 3rd party app that provides many
@ptone
Django member
ptone added a line comment Feb 24, 2013

not trying to be a curmudgeon, but I'm wary of including links to specific 3rd party apps in what can be a fast moving world of web dev

@reinout
reinout added a line comment Feb 24, 2013

Agree. Zapped.

@reinout
reinout added a line comment Feb 24, 2013

In the final version it is back in after discussion on IRC, but then in the form of a link to https://www.djangopackages.com/grids/g/storage-backends/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ptone ptone commented on the diff Feb 24, 2013
docs/howto/static-files.txt
-
- STATICFILES_STORAGE = 'myproject.storage.S3Storage'
-
-Once that's done, all you have to do is run :djadmin:`collectstatic` and your
-static files would be pushed through your storage package up to S3. If you
-later needed to switch to a different storage provider, it could be as simple
-as changing your :setting:`STATICFILES_STORAGE` setting.
-
-For details on how you'd write one of these backends,
-:doc:`/howto/custom-file-storage`.
-
-.. seealso::
-
- The `django-storages`__ project is a 3rd party app that provides many
- storage backends for many common file storage APIs (including `S3`__).
+Deployment
@ptone
Django member
ptone added a line comment Feb 24, 2013

I'm a bit confused - what is "deployment" if not deployment in production (meaning anything non-local-dev)?

@ptone
Django member
ptone added a line comment Feb 24, 2013

After looking through your rendered version (diffs suck for docs review ;-) I see that this is a relatively short introduction followed by a link to the new doc. I'm bing a bit picky here, but really your new doc is just "deployment", I'd consider taking out the "to production" part, as you may use one of the explained techniques for staging, another for production etc.

@reinout
reinout added a line comment Feb 24, 2013

Yeah, it is also for staging and testing and...
I've removed "to production" from the other doc's title.

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

Thanks for the solid amount of work on this - I need to read it again in non-diff form, I realize now I made some line comments on things that were just moved around from the original docs.

I do think that the basic split is "local-dev" use, and "everything else" which would cover staging and production environments.

@ptone ptone and 1 other commented on an outdated diff Feb 24, 2013
docs/howto/static-files.txt
-.. note::
-
- If you've used the `django-staticfiles`_ third-party app before, then
- ``django.contrib.staticfiles`` will look very familiar. That's because
- they're essentially the same code: ``django.contrib.staticfiles`` started
- its life as `django-staticfiles`_ and was merged into Django 1.3.
-
- If you're upgrading from ``django-staticfiles``, please see `Upgrading from
- django-staticfiles`_, below, for a few minor changes you'll need to make.
-
-.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
-
-Using ``django.contrib.staticfiles``
-====================================
+===================================
+Managing static files (CSS, images)
@ptone
Django member
ptone added a line comment Feb 24, 2013

I think 'static files' are defined quickly enough not to need the examples in the heading here.

@reinout
reinout added a line comment Feb 24, 2013

The title is what ends up in the TOC and search results. Adding "css, images" makes the title much clearer when used separately.

@reinout
reinout added a line comment Feb 24, 2013

From irc: "I like it" and "Other frameworks call it "assets" to people might not find "static files" unless we help 'em a bit."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@reinout reinout Various adjustments.
- Included fixes for comments made on github.

- More sphinx constructs.

- Fixed a sphinx link.

- Improved wording.
9d04715
@reinout reinout commented on the diff Feb 24, 2013
docs/ref/contrib/staticfiles.txt
.. highlight:: python
-.. function:: django.contrib.staticfiles.views.serve(request, path)
@reinout
reinout added a line comment Feb 24, 2013

This seemed the only way I could get the link to this function to work.

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

Hi Reinout,

After giving it some thought I'd like to propose changing the name to: "Serving static files (CSS, Images)" or even "How to serve static files (CSS, Images)". Reinout what is your opinion? It might do better when users google for their questions (and we have to beat Stack Overflow dont we? :)).

In addition, there is a title "Configuring static files" which should probably be "Configuring staticfiles" which is the package name, or maybe even: "Configuration".

@wimfeijen

PS I must say I really like it! But I am being subjective. :)

@reinout

@wimfeijen I'm leaving it as-is right now. Ready for check-in. Tweaks can be done later. Now we have to wait for the tutorial (pull requst #795) to be ready as they have to be accepted simultaniously.

@carljm carljm and 1 other commented on an outdated diff Feb 25, 2013
docs/howto/static-files.txt
-.. currentmodule:: django.conf.urls.static
-.. function:: static(prefix, view='django.views.static.serve', **kwargs)
+During development, you can serve user-uploaded media files from
+:setting:`MEDIA_ROOT`. using, the
@carljm
Django member
carljm added a line comment Feb 25, 2013

Extraneous period here?

@reinout
reinout added a line comment Feb 26, 2013

Well spotted. I've removed it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham timgraham closed this Mar 30, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment