NOTE: THIS DOCUMENT IS OUT OF DATE. PLEASE SEE
http://tiddlyweb.peermore.com/ FOR THE HEART OF TiddlyWeb DOCUMENTATION.
THIS DOCUMENT REMAIN HERE FOR HISTORICAL PURPOSES AND IN THE PERSISTENT
HOPE THAT IT WILL BE UPDATED.

Version 0.2 A work in progress.

Improvement suggestions most welcome.

This document assumes you have installed TiddlyWeb as a Python library
on your system, including a script called twanager in your $PATH.

If you are using TiddlyWeb from a source checkout these instructions
will still work if you have the tiddlyweb directory in your sys.path and
twanager in your $PATH.

What were going to do is create a directory where you TiddlyWeb data and
configuration will be stored and then run the server from that location.

These instructions assume you are working from a unix-like shell. Where
you see '$' starting a line, that's a line for you to type into the
shell. Other shells like the Windows command line will work similarly,
perhaps with slight changes to the syntax. Before each block of $ lines
will be an explanation of what you're about to do. Each block is
followed by what should have happened. When you are to fill in a piece
of information yourself, it is bracketed like this:

  $ mkdir <directory name>

That means you should type 'mkdir', a space, the name of the
directory you are creating and then press return.

Let's begin.

1. Get Where You Need to Be

The first step is to choose a directory where you will build the
system. This can be anywhere that is convenient for you. Since
version 0.6 of tiddlyweb, this directory will be automatically
created for you using a twanager command. So all you need to do
for now is go to the directory that will contain the directory
you wish to create.

Next we'll confirm that you have access to the twanager (TiddlyWeb
Manager) command. You'll use this command quite a bit. It is a tool for
managing the TiddlyWeb server and data store. If you run it without any
arguments you should get a list of possible commands. Try it:

  $ twanager

You should see something like this:

   adduser: Add or update a user to the database: <username> <password> [[role] [role] ...]
       bag: Create or update a bag with the json text on stdin: <bag name>
  from_svn: Import one or more plugins, tiddlers or recipes from tiddlywiki subversion.
    imwiki: Import a Tiddlywiki html file into a bag: <filename> <bag name>
  instance: Create a tiddlyweb instance with default plugins in the named directory.
    recipe: Create or update a recipe with the recipe text on stdin: <recipe name>
    server: Start the server: <hostname or ip number> <port>
   tiddler: Import a single tiddler into an existing bag from stdin: <tiddler_name> <bag name>
     usage: List this help

If it doesn't work then you are in an unsual situation. First make sure
the stuff in README checks out okay and then contact TiddlyWikiDev for
some assistance if not.

2. Create Your Base Store

By default, TiddlyWeb uses a text based storage system with its
root in a directory named 'store' in the same directory from which
the server starts. That's the directory we are in right now.

As of version 0.6, the store directory and subdirectories are
automatically created for you when you first use the store, so
this will be done in the next step.

3. Create Your First Bag

TiddlyWeb tiddler content is stored in bags. Each bag gets a name.
If you have two tiddlers with the same title, but in two differently
named bags, they are two different tiddlers. In TiddlyWeb when we
refer to a tiddler, we refer to it using the combination of its
bag's name and its tiddler title.

To put content into a TiddlyWeb server, we first have to create a bag.
Bags have permission structures which can be set. For now we will ignore
those and use the default, which is that everyone can read or write
content from and to a bag.

The first bag we'll create is one that will contains the two plugins
that make content automatically synchronize back to the TiddlyWeb server
after it has been edited in a TiddlyWiki. We'll call this bag
'system'. Because this is something you are likely to do quite a bit
if you install TiddlyWeb often, there's a twanager command that encapsulates
multiple steps in one. Remember the directory name you chose above, we'll
use that now to create an "instance" of TiddlyWeb.

  $ twanager instance <directory name>

If you get no error message it worked. You can confirm that it did
by doing

  $ ls -lR <directory name>

You should see a list of several files including a directory:
'<directory name>/store/bags/system'

The instance command has:

 * created <directory name> directory
 * created a storage directory
 * created a bag name common where new content will be saved
 * create a bag named system where plugins for automatic saving
   are kept
 * imported the ServerConfig, ServerSideSavingPlugin and TiddlyWebAdaptor
   plugins from svn.tiddlywiki.org into the system bag
 * put an empty configuration file (tiddlywebconfig.py) in
   <directory name>

The instance command needs access to the internet (over HTTP). If
you are behind a firewall that users a proxy, you will need to make
sure that http_proxy is set in your environment to the details of
your proxy server. Something like this:

    http_proxy=http://<username>:<password>@<proxy host>/

For the next steps you'll need to be in <directory name> so
change into it:

  $ cd <directory name>

If you want to add other content from svn.tiddlywiki.org or 
anywhere else on the web TiddlyWeb has built in support for
retrieving tiddlers and plugins from there. The twanager command
from_svn can retrieve tiddlers, plugins and full cook-style recipes
from HTTP and file URLs. If the instance command did not exist
we could have done:

  $ twanager from_svn system http://svn.tiddlywiki.org/Trunk/association/adaptors/TiddlyWebAdaptor.js

This would have installed the named plugin into the system bag,
if it existed.

4. Import A TiddlyWiki

Now, to bootstrap the collection of content on your TiddlyWeb server,
we're going to import one or more existing TiddlyWiki files into the
server, making a bag for each one. The first thing you need to do is
locate the TiddlyWiki HTML files and note their path on the filesystem.
If they are not on your system, download them using whatever method you
prefer (your browser, wget, curl, lwp_request, whatever it takes).

If you want to use the TiddlyWiki at tiddlyweb.com there are concrete
instructions for that at the end of this section. If you want to use
your own wiki file, carry on as follows:

To create a bag for each TiddlyWiki you wish to import we will use
the 'bag' command, replacing <bag name> with a unique name for each
TiddlyWiki. You can use spaces if you want, but if you do you need to
put the name in quotes. Remember which name goes with which TiddlyWiki.
Where you see ^D type ctrl-d.

  $ twanager bag <bag name>
  ^D

Once you have created the bags, import the wikis. The following
command will import one wiki into one bag.

  $ twanager imwiki <path to wiki file> <bag name>

If there are no errors from this, the tiddlers were imported. You can
confirm this by doing a directory list of the bag:

  $ ls store/bags/<bag name>/tiddlers

If your system has the 'ls' command that should return a list of the
tiddlers that were in the TiddlyWiki you have imported.

To use the TiddlyWiki at tiddlywiki.com as your sample wiki do the following.
You will need to have curl <http://curl.haxx.se/> available on your system.

  $ curl http://www.tiddlywiki.com > tiddlywiki.html
  $ twanager bag tiddlywiki < /dev/null
  $ twanager imwiki tiddlywiki.html tiddlywiki
  $ ls store/bags/tiddlywiki/tiddlers

You should see a large number of directories.

5. Create A Recipe

A recipe is a way to generate a collection of tiddlers by using tiddlers
from multiple bags. The recipe itself is a list of bags with optional
filter instructions. A filter selects only some of the tiddlers in a
bag, or sorts them. If there is no filter, all the tiddlers from the
bag are included. If there are tiddlers with duplicate names, the tiddler
from the last bag to have it is the one that is included in the collection
(the recipes are processed in order).

Your recipe gets a name. This name will be used in URLs that you publish,
so make it meaningful to you.

For this cookbook we'll ignore filters for now, and create a simple
recipe that allows the content you imported from one of your TiddlyWikis
to be presented through TiddlyWeb and be edited. For this you'll need
the name of the bag in which the tiddlers you want can be found. Use
that name in the instructions below. The two lines that follow the line
beginning with $ are lines for you to type (substituting the bag's name
for <bag name>. Make sure you type them correctly:

  $ twanager recipe <recipe name>
  /bags/system/tiddlers
  /bags/<bag name>/tiddlers
  ^D

If there are no errors, you should now have a recipe. It's time to
start the server.

6. Start The Server

TiddlyWeb comes with its own built in web server. TiddlyWeb can be run with any
sever you like, with some scripting, but for these current purposes the
built in server should work fine. By default the server runs on IP 0.0.0.0
and port 8080. You can choose different IP and port if you like. If you're
just experimenting on your local machine, the defaults should be fine. If 
for some reason 0.0.0.0 doesn't work, try 127.0.0.1. 

If you are running TiddlyWeb on a remote server you need to
choose the hostname of that server, and an available port.

Once you have figured these bits out you can start the server. If you are
using the defaults just do:

  $ twanager server

If you are using a custom IP number and port do:

  $ twanager server <ip number> <port>

You should see 'Starting CherryPy' and the $ prompt will not come
back. If you get an 'Address already in use' error some other service is
using the <port> you chose. Choose a different one.

It's time to go to your web browser. For the examples below
we'll use 0.0.0.0 and 8080 for ip number and port. Replace these
with the information you chose. On some systems 0.0.0.0 will not
work, you can try 127.0.0.1 instead. Go to:

  http://0.0.0.0:8080/

You should see a list containing 'recipes' and 'bags'. Click
around and see what you can discover. Going to

  http://0.0.0.0:8080/recipes/<recipe name>/tiddlers

will give you a list (in HTML) of tiddlers in the recipe.

  http://0.0.0.0:8080/recipes/<recipe name>/tiddlers.txt

will get you the same list as text.

  http://0.0.0.0:8080/recipes/<recipe name>/tiddlers.wiki

will get you a TiddlyWiki containing the tiddlers. Editing
one of those tiddlers should result in the tiddler being saved
back to the server. You can look at a tiddler from the recipe
on the server, as HTML, by going to:

  http://0.0.0.0:8080/recipes/<recipe name>/tiddlers/<tiddler title>

7. What Next?

Now you have a working TiddlyWeb server. You can stop and start it
whenever you like. TiddlyWeb will, by default, log requests to a 
file called 'tiddlyweb.log'. That file will be created in the same 
directory from which you start the server. If you would like to log
debugging information as well as requests change tiddlywebconfig.py
to look like this:

    config = {
        'debug_level': 'DEBUG'
    }

If you want to start the server and let it run in the background,
if you are on a Unix-based OS you can do this if you are using a
custom IP and port

  $ twanager server <ip number> <port> &

or this if you are using the defaults:

  $ twanager server

If you are not using the defaults but you don't want to type in the
IP number and port all the time you can add your choices to
tiddlywebconfig.py:

    config = {
        'debug_level': 'DEBUG',
        'server_host': {
            'scheme': 'http',
            'host': 'example.com',
            'port': '80',
        },
    }


If you encounter difficulties using TiddlyWeb contact the TiddlyWikiDev
Google Group, or contact the first author Chris Dent, <cdent@peermore.com>.

You can create bags and recipes as you need them for whatever functionality
you might need. With filters it is possible to create complex recipes.

TiddlyWeb is highly extensible, with a slowly growing collection of
plugins for using different storage mechanism, outputting different
types of a content and presenting additional URLs and interfaces. For
example TiddlyWeb can now run on Google's app engine service and it can
provide Atom feeds of lists of tiddlers.

TiddlyWeb is built as a REST API so can be flexibly accessed by a variety
of clients: a web browser, TiddlyWiki, scripting languages, other web
servers. By looking through the code and experimenting with the URLs
given to the server you'll see that TiddlyWeb can do far more than
explained in this document. Have fun with it.

8. What's Been Left Out?

This document makes no effort to explain some concepts in TiddlyWeb
which may be important to some users. Please look elsewhere in
the distribution and on the web for additional documentation. Things
not covered include:

* Filters on bags and recipes, both in recipes and in URLs. Any
  list of tiddlers may be filtered.
* User creation, authentication and authorizatin. TiddlyWeb has
  a flexible user handling system. By default no user is required
  and no restrictions are presented.
* TiddlyWeb is a Python WSGI application, and as such can be run
  under many different web servers without much issue.
* TiddlyWeb has a flexible storage system that makes it possible to
  create code which allows tiddlers, bags and recipes to be stored
  in many different systems (on disk, in a database, in Google's
  data system, in Amazon's S3, whatever you can think of).
