Administrators Documentation

You are here in order to run your own VTT instance. This documentation is based on using Ubuntu-based systems.

Requirements

Use requirements.txt to setup python.

Settings

All data of your VTT are stored inside ./local/share/pyvtt, including your settings.

Here is an example for a settings.json:

{
	"title": "MYVTT", 
	"expire": 2592000,
	"file_limit": {
		"token"      : 2,
		"background" : 10,
		"game"       : 15,
		"music"      : 10
	},
	"playercolors": ["#C52828", "#13AA4F", "#ECBC15", "#7F99C7", "#9251B7", "#797A90", "#80533F", "#21A0B7"],
	"links": [
		{
			"label" : "ROADMAP",
			"url"   : "/static/roadmap.html"
		}, {
			"label" : "TERMS",
			"url"   : "/static/terms.html"
		}
	],
	"shards": [
		"http://primary.my-vtt.com",
		"http://secondary.my-vtt.com"
	],
	"hosting": {
		"domain": "primary.my-vtt.com",
		"port": 80,
		"socket": "",
		"ssl": false,
		"hosting_url": "https://primary.my-vtt.com",
		"hosting_websocket_url": "wss://primary.my-vtt.com/websocket"
	},
	"login": {
		"type": "auth0",
		"domain": "example.eu.auth0.com",
		"client_id": "xxxx..",
		 "client_secret": "xxxxxx...",
		"icons": {
			"google": "https://www.google.com/favicon.ico",
			"discord": "https://assets-global.website-files.com/6257adef93867e50d84d30e2/6266bc493fb42d4e27bb8393_847541504914fd33810e70a0ea73177e.ico",
			"patreon": "https://c5.patreon.com/external/favicon/favicon.ico",
			"auth0": "https://cdn.auth0.com/website/new-homepage/dark-favicon.png"
		}
	},
	"notify": {
		"type": "email",
		"host": "smtp.my-mail.whatever",
		"port": "587",
		"sender": "[email protected]",
		"user": "my-vtt",
		"password": "your-secret-password"
	}
}

• title: Title of your VTT, shown in the HTML title
• expire: Timeout until a GM or game is expired and can be deleted by the cleanup script
• file_limit: Specifies maximum file sizes for tokens, backgrounds and games (ZIP). All numbers are referring MiB.
• links: A list of optional elements for the HTML footer (e.g. use for legal notice)
• shards: A list of optional servers. This is useful to build a status-page if you're running multiple VTT-servers
• hosting: Provides your your domain and port. It can also be ran using a unix socket. Optional SSL (only if run directly) requires certificates. In case of using a reverse proxy (nginx or similar), setup hosting_url and hosting_websocket_url.
• login: Specifies you GMs register and login to your VTT. If type is "" the developer login is enabled. Mostly use your Patreon API-Keys here.
• notify: Specifies how and who is notified about exceptions. If type is "" bottle will catch all exceptions and write to the standard output. Mostly configurate an E-Mail-Box here (Note: googlemail-addresses require to disable some security options in order to allow login via a python script)

FancyURL generation

In order to use the FancyURL generator, you'll need a fancyurl directory inside your settings directory. Place adjectives.txt, nouns.txt and verbs.txt with words there (separated by \n).

Running your VTT

Running directly

Just run ./vtt.py with optional arguments:

Commandline args:
    --debug       Starts in debug mode.
    --quiet       Starts in quiet mode.
    --local-gm    Starts in local-GM-mode.
    --localhost   Starts in localhost mode.

Debug Mode:     Enables debug level logging.
Quiet Mode:     Disables verbose outputs.
Local-GM Mode:  Replaces `localhost` in all created links by the public ip.
Localhost Mode: Restricts server for being used via localhost only. CANNOT BE USED WITH --local-gm

Note: --local-gm ignores the login settings and defaults to the developer's login mechanics.

If you want to use SSL when running directly, make sure to place a SSL certificate and privatekey inside your setting's ssl-directory and name them cacert.pem and privkey.pem.

Deployment with nginx

Example nginx configuration using a unixsocket:

daemon off;

error_log /tmp/vtt-nginx-error.log warn;
pid /tmp/vtt-nginx.pid;

events {}

http {
	map $http_upgrade $connection_upgrade {
		default upgrade;
		''      close;
	}

	access_log /tmp/vtt-nginx-access.log;
	
	upstream vtt {
		server unix:/tmp/vtt.sock fail_timeout=0;
	}
	
	server {
		listen 8080;
		server_name localhost;
		
		try_files $uri @vtt;
		
		location @vtt {
			proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
			proxy_set_header X-Forwarded-Proto $scheme;
			proxy_set_header Host $http_host; 
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection $connection_upgrade;
			
			proxy_redirect off;
			proxy_pass http://vtt;
		}
	}
}

Note: This configuration isn't well tested and not used by the author yet.

Auth via Patreon

In order to allow GMs to auth via Patreon's OAuth mechanism, you'll need a set of Patreon API-Keys. The whitelist is a list of optional Patreon-User-IDs which are granted access despite they are reaching the min_pledge (in cents) or not. Note to drop your port number from your URL if it iss a standard-port like 80 or 443 (not include it if you are testing on e.g. 8080, else Patreon login will result in mismatching redirect URIs.

Cleaning the database

To cleanup the database from expired records, stop the VTT, run cleanup.py and restart the VTT then.