Permalink
Browse files

git-svn-id: svn://cherokee-project.com/cherokee/trunk@1755 5dc97367-9…

…7f1-0310-9951-d761b3857238
  • Loading branch information...
1 parent 4eec0fb commit 56f24666ae87e730af1d545fe1ebe9cfc5d99866 taher committed Aug 6, 2008
View
5 doc/Makefile.am
@@ -92,7 +92,10 @@ media/images/admin_handler_onlylisting.png \
media/images/admin_handler_onlylisting_ex.png \
media/images/admin_launch.png \
media/images/tracelor.png \
-media/images/cherokee-tweak.png
+media/images/cherokee-tweak.png \
+media/images/admin_noconfig.png \
+media/images/admin_notrunning.png \
+media/images/admin_rule_regex.png
GENERATED_FILES = \
$(docdir_DATA)
View
2 doc/TOC.txt
@@ -22,7 +22,7 @@ The Cherokee Bundle
**************************
Configuration
**************************
- . Quickstart <1> link:config_quickstart.html[]
+ . link:config_quickstart.html[Quickstart]
. link:config_general.html[General]
. link:config_virtual_servers.html[Virtual servers]
- link:config_virtual_servers_rule.html[Rule Options]
View
169 doc/config_quickstart.txt
@@ -4,7 +4,7 @@ Configuration Quickstart
This section briefly describes the whole administration web interface
provided by link:bundle_cherokee-admin.html[cherokee-admin]. This is
the only recommended way of configuring Cherokee. If you are looking
-for development information, you should refer to the apropriate
+for development information, you should refer to the appropriate
section, especially link:dev_cherokee.conf.html[cherokee.conf] file
specification.
@@ -47,3 +47,170 @@ Overview
Walkthrough
~~~~~~~~~~~
+There is very little set up you must do to have a perfectly functional
+web server out of the box. Cherokee's default configuration can be
+used to serve any typical PHP-driven dynamic website.
+
+If you have a specific need, you should check out the recipes present in
+the 'Cookbook' section of the documentation. Among other subjects, you
+can find information about
+link:cookbook_optimizing_cherokee.html[Cherokee optimizations],
+setting up efficient link:cookbook_authentication.html[Authentication]
+mechanisms, or configuring several popular application frameworks.
+
+In this tutorial we will be setting up a system with a couple of
+virtual servers, PHP support, some redirection rules and a simple
+authentication mechanism.
+
+To follow this walkthrough you need to be running
+link:bundle_cherokee-admin.html[cherokee-admin]. This is an
+administration tool, so you will need system administrator rights.
+
+----
+# cherokee-admin
+Cherokee Web Server 0.8.0 (Aug 6 2008): Listening on port 9090, TLS disabled,
+IPv6 disabled, using epoll, 1024 fds system limit, max. 507 connections,
+single thread, 1016 fds
+Server 0.8.0 running.. PID=19611
+----
+
+Now you can access the administration interface simply by opening your
+web browser and visiting link:http://localhost:9090[http://localhost:9090]
+
+If your user doesn't have enough privileges you will be notified. Also
+if no configuration file exists you will be prompted to create one
+with the default settings.
+
+image::media/images/admin_noconfig.png[cherokee.conf not present]
+
+That is a good starting point. Right now your web server will not be
+running yet. We will only be using two of the available tabs to adjust
+some more settings: link:config_general.html[General] and
+link:config_virtual_servers.html[Virtual Servers].
+
+This is an example of what you'll be seeing:
+
+image::media/images/admin_notrunning.png[Server not launched]
+
+Of course, once we're done we will have to apply our changes and
+launch the server. The configuration changes must be submitted to the
+server, be it automatically if possible or by using the appropriate form
+submitting buttons. But no change is reflected in the configuration
+file until you `Apply` the changes. You can be sure of not damaging
+anything while playing around with `cherokee-admin`. At least not
+until you `Apply` the changes. Note that, if the Cherokee server is
+running, the applied modifications will also affect the instance being
+executed.
+
+This is what the `General` tab looks like:
+image::media/images/admin_general.png[General]
+
+We will only be modifying the *Server Permissions*. It usually is a
+poor choice to run services with super user privileges. Set both
+*User* and *Group* to `www-data`. Your system might already have
+another user account specifically for the purpose of running a
+webserver. Use that instead if so, or create the `www-data` user if
+you don't already have one.
+
+Next is the link:config_virtual_servers.html[Virtual Servers] tab:
+
+image::media/images/admin_vserver.png[Virtual server]
+
+When you start, you will only have one virtual server called
+`default`. You can begin by cloning it as `example`.
+While you are at it you should also append the following line to your
+`/etc/hosts` file (in Windows you will find this as
+`%WINDIR%\system32\drivers\etc\hosts`
+
+----
+127.0.0.1 example.net example.org
+----
+
+This is to allow your system to resolve requests for `example.net` or
+`example.org` locally. Of course, once you are out in the Wild (you
+know, in the Internet), you will need proper DNS records.
+
+`default`
+^^^^^^^^^
+We will leave default untouched except for the document root path,
+which we will change. This is done through the `Basics` tab.
+You could create by hand '/var/www/default' for example and set it up
+in the appropriate field.
+
+If you access your machine by IP or a DNS resolution points in that
+direction for any particular domain, the contents of your document
+root directory will be exposed ('/var/www' by default unless you
+changed that during the build process).
+
+Right now any file with the 'php' extension will be served after being
+processed by the PHP interpreter (you should have `php-cgi` installed
+in your system for this, though).
+
+Any requested file would be sent. If a directory is requested, a file
+called index.php or index.html will be served if it is present (the
+search will be performed in that order; you can configure this in the
+`Basics` tab). If not, a directory listing is offered instead. If you
+would want to prevent this behavior but would like to keep up
+serving whatever content is requested directly, simply change the
+`List & Send` handler for the `Static Content` handler.
+
+`example`
+^^^^^^^^^
+For now this virtual server is an exact copy of the untouched
+`default` virtual server. Create some new directories
+'/var/wwww/example', '/var/wwww/example/auth' and
+'/var/www/example/redir', and configure the first one as default
+document root path.
+
+Next, setup `example.net` and `example.com` in the `Domain names` tab.
+We'll erase everything in the *Targets* list within the `Behavior`
+tab, except the `default` rule. With this we'll only be able to serve
+static content.
+
+Accessing the URL http://example.org should now show a list of
+available files and directories under '/var/www/example/'.
+
+Now lets password protect the `auth` directory. Add a new `Directory`
+class rule pointing to `/auth`. Then, through the `Security` tab, add
+a `Validation Mechanism` under `Authentication`.
+
+The field `Realm` is mandatory. Lets set it as `Secured Area`.
+If you choose `PAM` and impose no more restrictions, only users with
+a local account in your system will be able to access the secured zone
+at http://example.net/auth
+Other mechanisms would work in a similar fashion but with their
+specific requirements. For example, had you chosen `Plain text file`
+instead of PAM you would have had to specify a `Password File`.
+For example, it could have been `/var/www/passwords.txt` with the
+following contents:
+
+----
+testuser1:password1
+testuser2:password2
+----
+
+Note that the rule must not be flagged as `Final`, or else no other
+rules will be applied afterwards and no access will be given to any
+contents. This is because at this point we have not defined any
+handler for the `/auth` rule and nothing would be served.
+
+Refer to the Cookbook for detailed examples on the different options.
+
+Lastly, lets configure a redirection rule by choosing a "Regular
+Expression" as the new rule type. Type the following regex: `^/rss.*$`
+Then, within the `Handler` selection tab specify a target: `/feed`
+
+image::media/images/admin_rule_regex.png[Regex]
+
+And voilà! A request of the form http://example.net/rss2 would be
+redirected to http://example.net/feed
+
+A much more general redirection could be one using these values:
+
+* *Regular Expression*::
+ `^/(.*)$`
+
+* *Substitution*::
+ http://www.cherokee-project.com/example/$1
+
+This would redirect every petition to a mirror hosted elsewhere.
View
BIN doc/media/images/admin_noconfig.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN doc/media/images/admin_notrunning.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN doc/media/images/admin_rule_regex.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 56f2466

Please sign in to comment.