[master] f53869e Rework tutorial

Per Buer perbu at varnish-cache.org
Fri Sep 7 15:23:19 CEST 2012 

commit f53869e8ed9680247531a8d0eaa50907de721b27
Author: Per Buer <per.buer at gmail.com>
Date:   Fri Sep 7 15:21:42 2012 +0200

    Rework tutorial

diff --git a/doc/sphinx/tutorial/index.rst b/doc/sphinx/tutorial/index.rst
index 15c8fdc..6444be9 100644
--- a/doc/sphinx/tutorial/index.rst
+++ b/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
diff --git a/doc/sphinx/tutorial/introduction.rst b/doc/sphinx/tutorial/introduction.rst
index 0d43623..cdbab1d 100644
--- a/doc/sphinx/tutorial/introduction.rst
+++ b/doc/sphinx/tutorial/introduction.rst
@@ -1,21 +1,18 @@
 .. _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.
+
diff --git a/doc/sphinx/tutorial/starting_varnish.rst b/doc/sphinx/tutorial/starting_varnish.rst
index 6c89f54..fcdc37c 100644
--- a/doc/sphinx/tutorial/starting_varnish.rst
+++ b/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`.

More information about the varnish-commit mailing list