Draft

This is a draft of a tutorial on how to do various administrative tasks in a TiddlyWeb instance. It ought to end up being a link to other stuff with some surrounding narrative.

Besides the information here, review the many FAQ and Howto tiddlers.

Creating an Instance

A TiddlyWeb service runs inside an instance. This is the directory which contains the configuration for the service (in tiddlywebconfig.py), a logfile named tiddlyweb.log and if the default text store is being used a store directory containing the tiddler, bag, recipe and user entities maintained in the service.

Plain TiddlyWeb

When running TiddlyWeb by itself (that is, not TiddlyWebWiki or TiddlySpace) the process of creating an instance is quite simple:

create a directory
optionally create a tiddlywebconfig.py within that directory
mount the service within a web server

Mount a Server links to tiddlers describing the many different ways to run a web server with TiddlyWeb.

TiddlyWebWiki

TiddlyWebWiki and other verticals (such as TiddlySpace) will usually include a script that will create an instance directory for you, supply it with a tiddlywebconfig.py that includes the necessary plugins, and create an initial store with the default entities.

The TiddlyWebWiki instance script is called twinstance. To see it in action try the following from a command line prompt:

twinstance mydir
cd mydir
cat tiddlywebconfig.py
ls store

When using twinstance the instance created defaults to the text store. To use a different one explore the technique described in TiddlyWeb with PostgreSQL.

Once an instance is created and the server has been configured the server needs to be started.

Starting and Stopping the Server

Managing the web server that is hosting the TiddlyWeb instance depends largely on which server is being used. However there are some common tasks that will be necessary to perform:

Starting

If the service is not running at all starting it means starting the web server. How this is done changes from server to server. If using the built in server it is possible to run twanager server from the command line, within the instance directory.

Many servers (for example Apache2 or Nginx) will usually have an initscript or service script that controls starting. This will be operating system dependent.

Stopping

Again this is entirely server dependent. For many servers the process running the web server will need to be stopped or killed, by hand. Servers that have been started from scripts will usually have stop commands.

For production services the server should only be stopped during maintenance windows.

Reloading Code and Configuration

When installing new code or updating the instance configuration, the web server will need to be restarted, reloaded or otherwise be made aware of the changes.

When using twanager server it is necessary to stop then start the server.

When Using Mod WSGI or Using nginx and uwsgi code can be reloaded by touching the wsgiapp.py file. This will signal to the hosting server that it should gracefully reload code and configuration. In some rare cases this will not work. When this happens restart the server.

Installing Server Side Plugins

Server side plugins are python packages or files which are used to add functionality to an instance. There are a large number of existing plugins and it is easy to create your own. Plugins can extend the command line tool twanager, add functionality to the web service or change how entities are stored or represented.

Adding plugins is done in most cases by updating system_plugins or twanager_plugins in tiddlywebconfig.py. When using a different store, server_store is updated. See also: config keys.

Logfiles

A TiddlyWeb instance may write to several different logfiles, depending on how it is being served. The hosting web server will have its own log or log files that record access and errors. TiddlyWeb itself maintains a log file in the instance directory named tiddlyweb.log by default. It can be changed by adjusting the log_file configuration setting.

What is written to the log file is controlled by the log_level setting.

When TiddlyWeb experiences a catastrophic error (wherein it is unable to process a request and must return a 500 response) a traceback of the error will show up in either the tiddlyweb.log file, the web server's error log or both. These tracebacks are extremely useful for determining what went wrong.

Usually there will be a timestamp associated with the error which should allow the error to be associated with a request in the web access log. Combining knowledge of the request with the error should make it possible to narrow down the cause, leading to an eventual solution.

Editing Entities

TiddlyWeb hosts four distinct entities. These are: recipe, bag. tiddler and user. These can be manipulated in multiple ways:

The HTTP API
The Python API
The interactive console
The twanager command line tool.

By default user entities may not be manipulated over the HTTP API, but this can be changed with a plugin.

examples forthcoming

Understanding Policies

Access to entities is controlled by policies. Each policy is made up of a set of constraints. These control who or what can read, edit, create, delete or manage the entity with which a policy is associated. Individuals do not have tiddlers policies themselves, but instead authorization for them is controlled by the bag that contains them.

The policy tiddler contains a description of the processing model.