Backlinks

TiddlySpace

20160313160639 cdent

This document describes how to install your own TiddlySpace server. Doing so has a fair few steps and can be quite an ordeal if you do not have prior experience with this sort of thing. If you are mostly interested in exploring TiddlyWeb to see if you want to use it, it is probably best to start first with Installing TiddlyWeb and then if that goes well and you want the additional TiddlySpace features, moving on to this.

If you already have your own TiddlySpace and are wanting to upgrade from an old version that uses tiddlywebplugins.mysql or tiddlywebplugins.mysql2 to tiddlywebplugins.mysql3 see @tiddlyweb-sql for critical information, especially these addenda for TiddlySpace.

TiddlySpace creates one large TiddlyWeb instance that, using just one database, supports many spaces on multiple hostnames. For example while there are over 9000 spaces on http://tiddlyspace.com there is only one instance, one database, one virtual host configuration in apache, and one WSGIDaemonProcess.

The instruction below assume a Debian or Ubuntu based Linux server. You will need to make adjustments for your own operating system. TiddlySpace is developed on OSX so can be made to work on a Mac, but it has never been tested on a Windows-based system.

The Steps

Install tiddlyweb according to the usual instructions
Install necessary extra binaries and libraries that will be required either by tiddlyspace or to build tiddlyspace. These include:
- mysql and libmysqlclient-dev
- the python-dev package (which provides Python.h)
- a compiler, usually gcc,
- (optional) apache2 and mod-wsgi
Install plugins required to run tiddlyspace. If you are using pip this can be done in one step:
```
pip install -U tiddlywebplugins.tiddlyspace
```

Create a mysql database. Only use the IDENTIFIED BY clause if you want a password for the database account. For a non shared machine, you may not.

mysql -u root -p
create database tiddlyspace \
   character set = utf8mb4 \
   collate = utf8mb4_bin;

GRANT ALL PRIVILEGES ON tiddlyspace.* TO '<tiddlydbuser>'@'localhost' IDENTIFIED BY '<dbpassword>';
quit

This step is only necessary if you wish to access the database with a username and password (which is a good idea if you are on a shared system but an additional bit of complexity if not). Change database setup in /usr/lib/python2.6/site-packages/tiddlywebplugins/tiddlyspace/config.py (on OS X this may be /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/tiddlywebplugins/tiddlyspace/config.py) adjusting for your Python version. If you want to run tiddlyspace just like tiddlyspace.com see the notes below.
```
'db_config': 'mysql://localhost/tiddlyspace?user=<tiddlydbuser>&passwd=<dbpassword>&charset=utf8mb4'}],
```
Choose a location where your tiddlyspace instance will live. I prefer a user's home directory. Whatever the location is, it should //not// be within the web server's DocumentRoot.
```
cd /home/tiddlyweb
```
Create a tiddlyspace instance in a directory called tiddlyspace_instance using the tiddlyspace command (installed when installing the tiddlyspace Python package):
```
tiddlyspace tiddlyspace_instance
```
cd to your tiddlyspace instance:
```
cd tiddlyspace_instance
```

Change the contents of tiddlywebconfig.py from:

config = {
    'system_plugins': ['tiddlywebplugins.tiddlyspace'],
    'secret': '<yoursecret>',
    'twanager_plugins': ['tiddlywebplugins.tiddlyspace'],
}

    config = {
        'system_plugins': ['tiddlywebplugins.tiddlyspace'],
        'secret': '<yoursecret>',
        'twanager_plugins': ['tiddlywebplugins.tiddlyspace'],
        'server_host': {
            'scheme': 'http', # or https
            'host': '<yourhostname>',
            'port': '80'
        }
    }

Get wsgiapp.py from github:

wget http://github.com/tiddlyweb/tiddlyweb/raw/master/wsgiapp.py

Create a virtual host configuration in apache's httpd.conf (or related files). If your prefer nginx see WorkingNginxConfig:

<VirtualHost *:80>
    ServerName <yourhostname>
    ServerAlias *.<yourhostname>
    #Include tiddlyspace-aliases.conf
    AllowEncodedSlashes On

    ErrorLog /var/log/httpd/tiddlyspace.com-error.log
    CustomLog /var/log/httpd/tiddlyspace.com-access.log combined

    # It is very important to run mod-wsgi in Daemon mode. This insures
    # that it does not run as the same user as the web server.
    # set user and group to the user and group that will run tiddlyweb
    WSGIDaemonProcess tiddlyweb user=tiddlyweb group=tiddlyweb processes=2 threads=10 \
        stack-size=524288 display-name=%{GROUP} maximum-requests=500
    WSGIProcessGroup tiddlyweb
    WSGIPassAuthorization On
    WSGIScriptAlias / /home/tiddlyweb/tiddlywebs/tiddlyspace/wsgiapp.py
</VirtualHost>

In your favorite browser, go to your yourhostname and register yourself as user yourusername
In the shell, make this user an ADMIN:
```
twanager addrole <yourusername> ADMIN
```

And then visit the hostname in your browser.

32 bit vs. 64 bit issue

You may be getting an error that looks like this:

    ERROR: ImportError: ("couldn't load store for tiddlywebplugins.tiddlyspace.store: dlopen(/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/_mysql.so, 2): no suitable image found.  
    Did find:\n\t/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/_mysql.so: mach-o, but wrong architecture, No module named tiddlywebplugins.tiddlyspace.store",)

If so see these instructions to resolve 32 bit vs. 64 bit issue

Tricky Bits

Making sure the right requirements are in place on the system so that the Python modules can properly build. This means that a proper compiler is present, along with various C libraries. What these are can usually be determined by inspecting the output of the pip command. It will report errors, usually talking about missing files.

Configuring the database and tiddlyspace so that the user or users that are allowed to access the database and the user that tiddlyspace will use to access the database are in agreement. On tiddlyspace.com the default configuration is used:

The database is configured to accept requests from the user tiddlyweb without a password, but only from localhost.
Tiddlyspace is configured to send requests as the db-user tiddlyweb, with no password.
The tiddlyspace instance runs as the unix user tiddlyweb out of the home directory (/home/tiddlyweb) of that user.

On shared servers this may not be the best idea. You probably want to or need to access the database as your own user. In that situation the default database configuration needs to be changed before the instance script is called otherwise no data will be put into the database during instance creation.

My feeling is that on a turnkey or vm style dedicated server for tiddlyspace, it is best to have a designated tiddlyweb user. Then people who are entitled to work directly on the server ssh into their own accounts and run commands as sudo -u tiddlyweb <command> or ssh directly into the tiddlyweb account (the former is easier to audit in case there are problems).

If you are testing a tiddlyspace installation on a server on which you have not yet set up DNS you may find it useful to adjust the /etc/hosts file on both your server and the testing client machines. See this groups thread for more info.

Another option is to use dnsmasq as explained in this HOWTO. This makes it so /etc/hosts doesn't need to be messed with for each test user.

FAQ

Q: bpursley: Comment/Question: http://tiddlyspace.com/bags allows me to "peruse" but not necessarily change all bags, including tiddlers flagged as private. Is this how "private" was intended? It seems like a funky behavior for "private".

When you are viewing bags you are viewing them as your current user and you are able to see those bags which you can read. When a different user views the same URI, they will see a different list of bags. These behaviors are controlled by the policy on the bag. Being able to 'read' a bag does not mean that you will be able to delete or edit tiddlers within it. The policy controls that too.