Rework tutorial

doc/sphinx/tutorial/index.rst

@@ -4,11 +4,22 @@
 The Varnish Tutorial
 %%%%%%%%%%%%%%%%%%%%
 
-What is a tutorial, anyway? Let's start off by including some of the stuff we chucked out of the previous tutorial - now "users guide"
+What is a tutorial, anyway?
+
+Scope: Lets start off by explaining the basic concept. Cover the
+following points:
+- what is a cache. How does Varnish work?
+- how do I start it.  
+
+Then we hand things over to the user guide. 
+
+Let's start off by including some of the  stuff we chucked out of the
+previous tutorial - now "users guide"
 
 .. toctree:: :maxdepth: 1
 
    introduction
+   web_accelerator
    starting_varnish
    putting_varnish_on_port_80
    backend_servers

doc/sphinx/tutorial/introduction.rst

 .. _tutorial-intro:
 
 What is Varnish?
-----------------
-
-Varnish Cache is a web application accelerator also known as a caching
-HTTP reverse proxy. You install it in front of any server that speaks
-HTTP and configure it to cache the contents. Varnish Cache is really,
-really fast. It typically speeds up delivery with a factor of 300 -
-1000x, depending on your architecture.
+-------------
 
+Varnish Cache is a web application accelerator. It can also be called
+a HTTP reverse proxy. The next chapter :ref:`tutorial-web-accelerator`
+will go into detail on what Varnish is.
 
 Performance
 ~~~~~~~~~~~
 
-Varnish performs really, really well. It is usually bound by the speed
-of the network, effectivly turning performance into a non-issue. We've
-seen Varnish delivering 20 Gbps on regular off-the-shelf hardware.
+Varnish has a modern architecture and is written with performance in
+mind.  It is usually bound by the speed of the network, effectivly
+turning performance into a non-issue.
 
 Flexibility
 ~~~~~~~~~~~
@@ -23,15 +20,34 @@ Flexibility
 One of the key features of Varnish Cache, in addition to it's
 performance, is the flexibility of it's configuration language,
 VCL. VCL enables you to write policies on how incoming requests should
-be handled. In such a policy you can decide what content you want to
-serve, from where you want to get the content and how the request or
-response should be altered. You can read more about this in our
-tutorial.
+be handled. 
 
+In such a policy you can decide what content you want to serve, from
+where you want to get the content and how the request or response
+should be altered. 
 
 Supported plattforms
-~~~~~~~~~~~~~~~~~~~~
+-----------------
 
 Varnish is written to run on modern versions of Linux and FreeBSD and
 the best experience is had on those plattforms. Thanks to our
 contributors it also runs on NetBSD, OpenBSD and OS X.
+
+About the Varnish development process
+-------------------------------
+
+Varnish is a community driven project. The development is overseen by
+the Varnish Governing Board which currently consist of Poul-Henning
+Kamp (Architect), Rogier Mulhuijzen (Fastly) and Kristian Lyngstøl
+(Varnish Software).
+
+Getting in touch
+-------------
+
+You can get in touch with us trough many channels. For real time chat
+you can reach us on IRC trough the server irc.linpro.net on the
+#varnish and #varnish-hacking channels.
+The are two mailing lists available. One for user questions and one
+for development discussions. See varnish-cache.org/mailinglist for
+information and signup.  There is also a web forum on the same site.
+

doc/sphinx/tutorial/starting_varnish.rst

@@ -3,49 +3,33 @@
 Starting Varnish
 ----------------
 
-I assume varnishd is in your path. You might want to run ``pkill
-varnishd`` to make sure varnishd isn't running. Become root and type:
+You might want to run ``pkill varnishd`` to make sure varnishd isn't
+already running. Become root and type:
 
-``# varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -T 127.0.0.1:2000 -a 0.0.0.0:8080``
+``# /usr/local/sbin/varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -a :80``
 
 I added a few options, lets go through them:
 
 ``-f /usr/local/etc/varnish/default.vcl``
- The -f options specifies what configuration varnishd should use.
+ The -f options specifies what configuration varnishd should use. If
+ you are on a Linux system and have installed Varnish through packages
+ the configuration files might reside in ``/etc/varnish``.
 
 ``-s malloc,1G``
  The -s options chooses the storage type Varnish should use for
- storing its content. I used the type *malloc*, which just uses memory
- for storage. There are other backends as well, described in 
- :ref:tutorial-storage. 1G specifies how much memory should be allocated 
- - one gigabyte. 
-
-``-T 127.0.0.1:2000``
- Varnish has a built-in text-based administration
- interface. Activating the interface makes Varnish manageble without
- stopping it. You can specify what interface the management interface
- should listen to. Make sure you don't expose the management interface
- to the world as you can easily gain root access to a system via the
- Varnish management interface. I recommend tieing it to localhost. If
- you have users on your system that you don't fully trust, use firewall
- rules to restrict access to the interface to root only.
-
-``-a 0.0.0.0:8080``
- I specify that I want Varnish to listen on port 8080 for incomming
- HTTP requests. For a production environment you would probably make
- Varnish listen on port 80, which is the default.
+ storing its content. I used the type *malloc*, which uses memory for
+ storage. There are other backends as well, described in
+ :ref:`user-guide-storage`. 1G specifies how much memory should be
+ allocated - one gigabyte. 
 
 Now you have Varnish running. Let us make sure that it works
-properly. Use your browser to go to http://192.168.2.2:8080/
+properly. Use your browser to go to http://192.168.2.2/
 (obviously, you should replace the IP address with one on your own
 system) - you should now see your web application running there.
 
-Whether or not the application actually goes faster when run through
-Varnish depends on a few factors. If you application uses cookies for
-every session (a lot of PHP and Java applications seem to send a
-session cookie if it is needed or not) or if it uses authentication
-chances are Varnish won't do much caching. Ignore that for the moment,
-we come back to that in :ref:`tutorial-increasing_your_hitrate`.
+There are many command line options available for Varnish. For a walk
+through the most important ones see :ref:`users-guide-command-line` or
+for a complete list see :ref:`ref-varnishd`. 
 
-Lets make sure that Varnish really does do something to your web
-site. To do that we'll take a look at the logs.
+Ignore that for the moment, we'll revisit that topic in the Users
+Guide :ref:`users-guide-increasing_your_hitrate`.