Static files - need clarification of apparent contradiction in documentation

Using Django
1

I am planning to build and deploy a Django site, and I want to understand what I’m doing first (rather than just following a list of instructions). I am confused by what seems to be an internal contradiction in the Django docs about static files. According to Django’s deployment instructions, if I have a simple setup with my Django app and my static files on the same server, I should:

  • Push your code up to the deployment server.
  • On the server, run collectstatic to copy all the static files into STATIC_ROOT.
  • Configure your web server to serve the files in STATIC_ROOTunder the URL STATIC_URL.

But Django’s instructions about setting STATIC_ROOT seem to include the opposite instructions (in a “warning” box no less), which say this about STATIC_ROOT:

The absolute path to the directory where collectstatic will collect static files for deployment.

Example: "/var/www/example.com/static/"

If the staticfiles contrib app is enabled (as in the default project template), the collectstatic management command will collect static files into this directory. See the how-to on managing static files for more details about usage.

Warning

This should be an initially empty destination directory for collecting your static files from their permanent locations into one directory for ease of deployment; it is not a place to store your static files permanently. You should do that in directories that will be found by staticfiles’s finders, which by default, are 'static/' app sub-directories and any directories you include in STATICFILES_DIRS.

So I’m confused. According to the warning in this second set of instructions, STATIC_ROOT “should be an initially empty destination directory for collecting your static files from their permanent locations into one directory for ease of deployment; it is not a place to store your static files permanently.”

But if it’s not a place to store them permanently, why do the deployment instructions (the first set above) tell me to “Configure your web server to serve the files in STATIC_ROOT”?

I’m just trying to set up a simple one-server deployment, and I just want to know what directories I need to create. I am unable to understand this based on the instructions I am reading. I would greatly appreciate clarification. Thanks!

(PS The forum would only let me post something with two links, so I apologize for the lack of links in the quoted material.)

2

I can see the possible confusion there.

I would call it an issue of perspective. You can think of STATIC_ROOT as being “owned by” the server, not by you.

“You” are not supposed to store files there directly. It’s not a “source” for static files, it’s a destination for them.

So you shouldn’t think of STATIC_ROOT as a permanent home. It’s not usually part of your project directory structure, and shouldn’t be checked into your repo. In some common deployment scenarios, you may not even have access to it. What you definitely don’t want to do is place files there yourself. It’s a location for collectstatic to manage.

The collectstatic command is going to copy static files from their sources (from inside your project and from libraries) to STATIC_ROOT. And, if you use the -c parameter in your collectstatic command, it’s going to clear out that target directory before copying files into it. (Good for removing obsolete files)

3

Thank you so much @KenWhitesell for this response! I think I understand, but let me put this in my own words to confirm:

STATIC_ROOT is a perfectly acceptable [perhaps even the default?] location from which to serve static files associated with your Django app. You do this by configuring your web server to deliver those files from STATIC_ROOT.

Note, however, that the files that are served out of STATIC_ROOT are generated and placed there programmatically, not manually, and they are periodically regenerated as needed. Because the files in STATIC_ROOT are generated programmatically, (1) you should not place files there manually (that would be the opposite of placing them there programmatically, and (2) you should not track the files in STATIC_ROOT in source control (the files you will track are the source files, located within your app, not the files generated from those source files and placed in STATIC_ROOT).

Is that right? If so, it’s analogous to Jekyll, which programatically generates a _site folder that contains the files that are served to the end user but that are not tracked, because the _site folder is programmatically generated from source files.

Also, if that’s right, I’ll try to figure out how to suggest an edit to the documentation. The statement in the “Warning” that STATIC_ROOT is “not a place to store your files permanently” is what really confused me. In fact (again, if I understand correctly), it is a place from which your files can permanently be served. It’s simply not a location where the source, i.e., non-programmatically-generated, static files are stored.

Does this make sense?

4

I would concur with your rewording.

However, I’m not sure I’m personally comfortable with any use of the word or concept of “permanent” when it comes to STATIC_ROOT. They’re not intended to be permanent in that it’s intended to remove / replace those files every time you do a deployment. It’s a “temporary” holding place in that they’re only supposed to be there until the next deployment.
I would go so far as to describe it as the place from which static files are to be served, but personally, I would avoid any temporal attributes being applied to it.

5

Thanks! I think it’s fair to say that the location is permanent but its contents are not. It’s like a refrigerator. The refrigerator is where I always store food; it’s a permanent location for food. But I don’t store food there permanently; the food gets replaced as it’s used (or goes bad).

But now we are just having fun nitpicking about language. We understand each other. And I appreciate your help very much!

1 Like