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.
- create a directory
- optionally create a tiddlywebconfig.py within that directory
- mount the service within a web server
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
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:
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 serverfrom 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.
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
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.
twanager serverit 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.
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.
By default user entities may not be manipulated over the HTTP API, but this can be changed with a plugin.
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.