COMPRESS_OFFLINE setting clarification

[alfetopito]

Hey there!

I spent awhile struggling to get django-compress working together with whitenoise on Dokku (you know, almost Heroku).

I stared for some time at this ticket #486 (comment) and tried several things, all without success.

Even disabled whitenoise's caching, and still no luck.

I had come across the COMPRESS_OFFLINE setting, but had ignored it since compress --force created the needed file, and it states that when it is set, the compressing will be ALSO done offline together with request/response loop.

I had thought: "If it won't disable online compression and the --force flag works, why bother?"

Turns out I need to set this to COMPRESS_OFFLINE = True to finally get it working.

Before setting this flag, the file name set on my html didn't match the one on the file system.

So, I just suggest the docs reflect the need to set that flag if working offline. At least I had to.

[diox]

COMPRESS_OFFLINE makes {% compress %} tag use offline compression at request/response cycle time. It's a specific way of using compressor, entirely optional, as explained in http://django-compressor.readthedocs.org/en/latest/scenarios/

The compress management command is only really meant for use with offline compression, that's why you have to use --force if offline compression is not enabled. If offline compression is disabled and you run the command with --force, that will generate files it would normally generate during the request/response cycle (and the offline manifest, which will not be used, since offline compression is disabled), but with the caveats explained in the doc I linked above. It's usually a bad idea.

Feel free to submit a PR with specific documentation tweaks once you have a good idea of the clarifications you seek - it's not clear to me what you'd want the docs to say at this point (probably because I'm fairly familiar with the way compressor works already).

[diox]

Also worth checking out http://django-compressor.readthedocs.org/en/latest/behind-the-scenes/

[alfetopito]

COMPRESS_OFFLINE makes {% compress %} tag use offline compression at request/response cycle time.

Oh, I see. That makes more sense.

What got me confused was the ALSO. If you have the flag set, does the compression still happens at request time? I assume it doesn't from your response.

Then when using COMPRESS_OFFLINE it is mandatory to run manage.py compress at least once to generate the pre-compressed files, correct?

If I understood it now, this could better describe it (although there is room for improvement):

Boolean that makes {% compress %} tag use offline compression at request/response cycle time. 
Use in combination with `manage.py compress` to pre-compress CSS and JavaScript files.
Recommended way of serving in Heroku like environments.

[diox]

What got me confused was the ALSO. If you have the flag set, does the compression still happens at request time? I assume it doesn't from your response.

It does not. If COMPRESS_OFFLINE is True, and compressor can't find the hash corresponding to a {% compress %} block contents in the offline manifest, it will raise an OfflineGenerationError exception. Some users have asked for a fallback but I've always been against that.

Then when using COMPRESS_OFFLINE it is mandatory to run manage.py compress at least once to generate the pre-compressed files, correct?

Yes, it should be done at each deploy.

I'll review your documentation suggestion if you make a PR with it :) - I'd probably remove the note about Heroku, there are a lot of users struggling with Heroku, and I don't have an account myself to test with (or time to do it) so I don't want to promise it works.

[stcqu]

Compressor's online mode doesn't work on Heroku because Whitenoise doesn't by default pick up changes to the static folder after the app has been loaded. That can be changed by changing the WHITENOISE_AUTOREFRESH setting to true, but it's really only meant for development mode.

To use Compressor in production you should set COMPRESS_OFFLINE=True and run python \app\manage.py compress using Heroku's post_compile hook. You may want to take a look at heroku-django-cookbook for more information.

Might also be applicable to issue #486