Installation

This describes the process for installing a brand-new Tworld realm on a server. It's not very complete, but I've verified that one can get a realm up and working.

Remember that Tworld does not contain any references to Myst. If you set up a server, you will see “portals” rather than “linking books”, “worlds” rather than “Ages”, and so on.

Requirements

 * Python 3 (3.3 or later)
 * MongoDB (2.4 or later) (not tested with 2.5 or 2.6)
 * Tornado (3.1 or later) (not tested with 3.2)
 * PyMongo (2.4 or later)
 * Motor (0.1)

Typically you will install Python 3 and MongoDB with your package manager; on MacOS, I use Homebrew. Python comes with its own package manager, pip3; use this to install Tornado, PyMongo, and Motor.

To fetch Tworld itself, download the source code from Github or use git:

git clone https://github.com/erkyrath/tworld.git

Note: the latest version of Motor (0.1.2) specifies the not-quite-latest version of PyMongo (2.5.0). This is a nuisance. I am currently using PyMongo 2.5.2 with Motor 0.1, which seems to work with a simple Mongo configuration. Do not try this with replica sets.

The Overview
Tworld runs as a trio of daemon processes (mongod, tweb, and tworld). mongod is a "no-sql" database server. tweb handles player web connections, and also the world-building interface. tworld maintains the realm state. All three talk to each other; all three must be running for Tworld to be functional.

To run these processes, you will need a private server, or a shared compute service such as Linode or Amazon EC2. Tworld is not suitable for a shared web-hosting service; these usually forbid long-running processes such as chat and MUD apps.

The tworld directory (as fetched from Github) contains the following:


 * twsetup.py: Script to create a fresh realm. (Also some other administrative tasks.)
 * tweb.py: The front-end web server script.
 * tworld.py: The back-end world server script.
 * twloadworld.py: Create a world based on the contents of a text file. (This is an unsupported hack; not recommended.)
 * tworld.conf: Sample Tworld configuration file. (Used by all four Python scripts.)
 * mongod.conf: Sample MongoDB configuration file.
 * lib: Python modules used by the four scripts.
 * template: Web page templates. These determine the appearance and content of the Tworld site.
 * static: Web content used by clients (Javascript and CSS files).
 * requirements.txt: Python install requirements.
 * README: Overview of the project.
 * LICENSE: MIT open-source license.
 * CONTRIBUTING: Notes on contributed code.

Steps
Make sure everything described above is installed.

Make sure MongoDB is running. (Your package manager may have started it as part of the install process.) If you can run the  command-line shell, then MongoDB is up.

(The  file is a simple setup that works with Tworld. But the default configuration that came from your package manager should be fine.)

Edit the  to your liking. You should definitely set these fields:


 * hostname: The public server name
 * admin_email: Address to use for the Admin account
 * email_from: Address to be used when sending password recover email
 * cookie_secret: Put in random characters as a cookie encryption key
 * base_path: Location of the tworld directory on your server

Run the setup script:

python3 twsetup.py --config=tworld.conf

It should report:

No admin player exists; creating. No world exists; creating start world.

Now you need to set the Admin account password. You could use the normal password-recovery link for this, but it's easier to use a special option of the twsetup.py script:

python3 twsetup.py --config=tworld.conf --resetpw=Admin

This will prompt you for a password, twice.

Password: (enter password) Password: (enter password again)

The realm is now set up, with a single world and a single location.

You can now start the tweb and tworld processes. For testing, you can simply launch these in two separate terminal windows. For a production server, you'll put them in  or wherever makes sense on your system.

python3 tworld.py --config=tworld.conf python3 tweb.py --config=tworld.conf

Each process will start up and remain running, displaying log activity on stdout.

At this point the realm is fully operational. In a web browser, go to the server URL. If you are running on a private machine, this will be http://localhost:4000/. You should be able to log in as "Admin" with the password you specified.

The Admin account has build access by default, so you can go into the build interface and begin creating the start world.

Server Customization
You can tweak the HTML source (in the templates directory) and the CSS files (in the static directory) however you like. (It's probably a bad idea to mess with the Javascript source.)

TODO:


 * Talk about the localization file (twsetup.py --localize)
 * Talk about config DB variables (startworldloc, firstportal)
 * Introduction to the  shell and how to peer into the database