[Cookbook][Cache] Added config example for Varnish 4.0

[thierrymarianne]

Q	A
Doc fix?	[yes]
New docs?	[no]
Applies to	[all]
Fixed tickets	[]

After upgrading to Varnish 4.0, I've noticed the documentation was not really up-to-date anymore:

• according to https://www.varnish-cache.org/docs/4.0/whats-new/upgrading.html#req-not-available-in-vcl-backend-response,

  beresp is available in vcl_backend_response

• according to https://www.varnish-cache.org/docs/4.0/whats-new/upgrading.html#hit-for-pass-objects-are-created-using-beresp-uncacheable,

  hit_for_pass objects are created via beresp.uncacheable

Would this addition be enough in order to consider the documentation up-to-date in accordance with Varnish 4.0 upgrading guidelines?

[cordoval]

perhaps you want to make this // instead or a full docblock, though tbh not sure the cs on varnish

[thierrymarianne]

Ok!

[thierrymarianne]

@cordoval, Thank you for the quick feedback, do you believe it could be satisfying enough?

[cordoval]

imo is ok 👍 though i am not @wouterj or @xabbuh 😊

[thierrymarianne]

@cordoval Thanks! I look forward to hearing from them ^_^

[wouterj]

Related issue #4176

@dbu since you wanted to work on this chapter and varnish in general, can you have a look at this PR and share your thoughts?

[thierrymarianne]

@dbu Having a tab for each version of Varnish would be much better!

We could even offer a docker image running the proper version of varnish with corresponding configuration files (strictly inspired from the documentation) as well :)

[dbu]

i thought they changed that in varnish 4, at least for cache-control. not sure about the pragma, can you check what / if any of the below are still needed?

[thierrymarianne]

This comment should not be there, I should have gone from a blank page ... Sorry for that :/

[dbu]

i am not sure about no-cache in pragma and about private, though.

[thierrymarianne]

I'll check it out in the documentation. However, the best I could do would be to run the changes with the limited application I have and then revert to you with a mitigated opinion. I'm not sure it would cover all cases (and I don't think the documentation aims at covering it up or there would not be a Varnish documentation, right?).

[thierrymarianne]

@dbu I've replaced no-cacheand pragma with beresp.http.X-No-Cache.

[dbu]

yeah the tabs for varnish config would be really cool (/me looking at @fabpot)

i intend to review the documentation and clean up what is on http://foshttpcache.readthedocs.org/ and what belongs into the symfony documentation itself. in the FOSHttpCache we have configuration fragments that we include in the doc which are used in functional tests. i think wouter was talking about trying to find a way to test configuration examples from the doc. this would be a particularly challenging bit to test. not sure how much its worth the effort or if we rather keep the examples very minimal. if you want to provide a demo docker setup with a playground for varnish features, that would be cool. for a workshop, i did a vagrant setup (plain php examples without symfony) i can share with you if you want.

[thierrymarianne]

@dbu I would love to put together something like what you've suggested, a Docker image, which could be pulled and ran in order to check responses for specific request given some configuration 👍

[dbu]

i think some of these are not needed as they are the default behaviour. https://www.varnish-cache.org/docs/4.0/whats-new/upgrading.html#default-builtin-vcl-changes

and i would keep a comment similar to the one above that varnish 4 ignores the header by default.

[thierrymarianne]

@dbu A comment similar to varnish 3.0 comment has been added.

[xabbuh]

@thierrymarianne @dbu will something like the following be sufficient?

.. configuration-block::

    .. code-block:: varnish2

        // ...

    .. code-block:: varnish3

        // ...

    .. code-block:: varnish4

        // ...

[thierrymarianne]

@xabbuh To my mind, it would be more than perfect.

[dbu]

yep, exactly! (i would swap the order to show the current varnish by default and older versions on the not visible tabs, but whatever)

i wonder if this could be generic tabs rather than code tabs. then the content could specify the tab titles, in case we have other situations with alternatives. then we would still need to mark the tab content as code - but could also have varnish version specific comments (e.g. the doc links) inside the tab.

[xabbuh]

see fabpot/sphinx-php#20 and #4287

[thierrymarianne]

@xabbuh Varnish has its own DSL : https://www.varnish-cache.org/trac/wiki/VCL

[xabbuh]

@thierrymarianne Yeah, but unfortunately it's not supported by Pygments (which is used for rendering code blocks). So, I was wondering if we could use Ruby to get some syntax highlighting since the syntax seems to be similar.

[thierrymarianne]

@xabbuh Sure, if it provides a good enough syntax highlighting!

[xabbuh]

At least, it looks good locally. If you don't know any difference that may break it.

[thierrymarianne]

👍

[dbu]

cool. are you going to update to the new tabs feature now? or do you want to leave that for later (= for me)?

we still have the open question which cache directives we need to explicitly track vs those that are respected by default in varnish 4.

[thierrymarianne]

@dbu Sure (I intend to integrate the tabs feature) !

[xabbuh]

@thierrymarianne Note that this will only work once #4287 is merged.

[thierrymarianne]

@xabbuh Well noted!

[thierrymarianne]

@xabbuh The blank line has been added. Thanks for the reminder!

[dbu]

i did not run them in varnish, but they seem to be correct. lets merge and we can still fix later on if people discover issues.

[weaverryan]

Thanks so much everyone - this is a really great update in both content and readability. Cheers!

[weaverryan]

FYI - I just reverted this at sha: d07d5fe

I assumed that the sphinx-php extensions had been updated, but it looks like it hadn't, so the docs broke entirely. Let's get that fixed and then re-add this.

/cc @javiereguiluz @fabpot

[javiereguiluz]

@weaverryan please tell me if this is correct: thanks to this PR sent by @xabbuh we could add the following to the Sphinx-PHP extensions to make this document work:

config_block = {
    'varnish4': 'Ruby',
    'varnish3': 'Ruby',
    'varnish2': 'Ruby'
}

[dbu]

@javiereguiluz for FOSHttpCache we are doing this: https://github.com/FriendsOfSymfony/FOSHttpCache/pull/131/files#diff-1

[xabbuh]

@javiereguiluz That's right. But did you update the submodules on the build server?

[thierrymarianne]

@weaverryan @xabbuh @dbu Sorry for the inconvenience. I'm afraid I've been to optimistic on this one. Next time, I'll make sure I could reproduce the end product on my end without guessing.

[xabbuh]

@thierrymarianne I don't think it's your fault. It seems to be that the build process doesn't update the Git submodules and therefore uses an older version of the Sphinx extensions.

[thierrymarianne]

@xabbuh Let us say we all have our share of responsibility. Perhaps, we'll have a chance to discuss it in Madrid(?)

[wouterj]

@thierrymarianne this is a fault on the build process of the docs. They don't use the configuration and sphinx extension included in this repo, but a custom one. It was not completely in sync, causing this to break the docs.

So, don't worry. This has nothing to do with you, if you render this locally everything will be correct.

[stof]

@javiereguiluz couldn't the build process use the submodule of this repo for the extension, so that things working for the doc team and for Travis are also working when deploying ?

[weaverryan]

+1 - we've had a problem for a while with the sphinx-php submodule not actually updating to the latest version. I kind of took a "stab in the dark" at merging this and hoping for the best - that's my fault. But let's get this fixed up if we can :)

[wouterj]

Also a big +1 for me.

I know you are working on improve the documentation build process, including rendering the docs seperately instead of rendering all other docs (bundles, CMF) into the core docs. It would be nice if you could use the submodule and sphinx config included in the repo.

[fabpot]

I've deployed the new version of sphinx-php on the server, so everything should work fine now, right?

[wouterj]

yes. @weaverryan let's give it another shot, shall we?

[weaverryan]

I've just re-pushed this PR at sha: 23afdb3

Thanks @fabpot - I'll stop by the ZendCon Sensio booth later for a high-five (and a BlackFire.io demo if you'll give me one).

[xabbuh]

We will probably need another update for the best practices (see #4394).

[weaverryan]

Hey guys!

Sorry for the issues - I just reverted this again at sha: b3d96b8. We're still seeing the same build error during the full build (which happens about right now each day).

I'll wait to see if we can get another attempted fix up there!

[dbu]

would be nice if somebody who has access to the servers and the setup could track the thing down, rather than ryan having to break the live doc to test things out ;-)

[weaverryan]

I've created an issue - #4415 so that we don't lose this (since this PR is closed).

@dbu if it's helpful that I have access, then cool. If we get on top of the issue (e.g. if the deploy uses the git-submodule version that we commit), then that's cool for me too :).

Thanks!