Training material and related tools
This repository contains:
- Training material used for Varnish Plus training
- Source for the slides and book version
- A snapshot of munin graphs for use by instructors.
- PHP example-code for testing Varnish
- Build system for said training material
This is the training material Varnish Software uses for professional Varnish training courses. It is made available under a Creative Commons CC-BY-NC-SA license (see the LICENSE file for details) as a book.
The build system produces the book in PDF and HTML formats. The PDF format includes two editions, one as the book for trainees, and the other as slides for the trainer. You can download this book in PDF format from https://www.varnish-software.com/download-varnish-book.
- build/ - Created on make, contains PDF output, html-output and necessary images
- material/ - PHP files, mainly used by the web-dev material
- misc/ - Contains strange stuff. Including the old course (Linpro-source) and a patch for rst2s5 needed (and a pre-patched version).
- munin/ - Anonymized munin graphs for instructors
- NEWS - List of changes instructors should be be aware of from version to version.
- README - This file
- ui/ - Images, style-definitions for PDFs and CSS for the slides.
- util/ - Headers for the rst, tool to make version.rst, strip-class to remove an rst-class (for generating slides as PDF instead of s5).
- varnish_book.rst - course itself
- vcl/ - VCL files used in the course. Not a copy. Included directly as-is, and verified by make check. (note: If 'backend' is missing, a generic backend will be added on the fly during make check).
- src/ - Resource files for sphinx to export the book in HTML version.
This folder contains a Makefile to build the book in different formats.
Enter to the directory and type
maketo see the building targets.
Building the material
Install the following packages with their dependencies.
You also need the "Open Source" font type.
To check whether you have it, type
fc-match "Open Sans" in the terminal.
The command should output
OpenSans-Regular.ttf: "Open Sans" "Regular".
Otherwise, download it and install it.
Download the source code of this book:
git clone https://github.com/varnish/Varnish-Book.git
Compile the book:
All build-stuff is handled by make. The following is an incomplete list of targets:
- Builds book in PDF format
- Builds book in HTML and ePub format
- Builds slides in PDF format. This slides are to be used in a training course.
- removes build/
- Updates the default values of your Varnish installation. These values are the ones to be used in your book building.
util/param.rstrule and will call other rules to update the sources of the book.
Updating the training material
Read NEWS, and make sure you always add significant content changes in this file, so the instructor(s) can keep track of changes without reading commit logs.
Try to use only tip, warning and note boxes.
To change the layout, change
The syntax for indirect hyperlink targets (double underscores
__) is not the same for rst as for sphinx.
Thefore, for simplicity, avoid them.
More than two refereces per sentence is not supported by
Figures and tables must have a counter right before their directive. The counter must be as the following example:
.. figure 1
.. table 1
git-tag every time that the book is printed and distributed.
This subsection includes known issues for building the book in different formats.
Building with sphinx
- List of figures and list of tables do not work when the figure or table caption includes a reference. This is a limitation to create the PDF with sphinx.
- Fonts are not resized in notes or other cases such
This material is provided under a CC-BY-NC-SA license. The license is available from:
And a copy of the license is available in the LICENSE file.
Clarification: The Non-Commercial clause of the CC-BY-NC-SA license is intentionally vague in the original license. Varnish Software does not interpret reading of the material as commercial, regardless of context (e.g: You can read the material at work, for the benefit of your self and the company). The Non-Commercial clause is intended to block competition with other commercial training offerings and to prohibit commercial printing and selling of the book. If you have any doubt as to how this should be interpreted, please contact email@example.com for clarification before proceeding.