Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Reorganize docs into flat folder layout

Browse source
This commit is contained in:
Griatch 2020-06-17 18:06:41 +02:00
parent 106558cec0
commit 892d8efb93
135 changed files with 34 additions and 1180 deletions
Download patch file Download diff file Expand all files Collapse all files

171
docs/source/Setup/Apache-Config.md Normal file
View file

@ -0,0 +1,171 @@
# Apache Config
**Warning**: This information is presented as a convenience, using another webserver than Evennia's
own is not directly supported and you are on your own if you want to do so. Evennia's webserver
works out of the box without any extra configuration and also runs in-process making sure to avoid
caching race conditions. The browser web client will most likely not work (at least not without
tweaking) on a third-party web server.
One reason for wanting to use an external webserver like Apache would be to act as a *proxy* in
front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work
covered at the end of this page.
Note that the Apache instructions below might be outdated. If something is not working right, or you
use Evennia with a different server, please let us know. Also, if there is a particular Linux distro
you would like covered, please let us know.
## `mod_wsgi` Setup
### Install `mod_wsgi`
- *Fedora/RHEL* - Apache HTTP Server and `mod_wsgi` are available in the standard package
repositories for Fedora and RHEL:
```
$ dnf install httpd mod_wsgi
or
$ yum install httpd mod_wsgi
```
- *Ubuntu/Debian* - Apache HTTP Server and `mod_wsgi` are available in the standard package
repositories for Ubuntu and Debian:
```
$ apt-get update
$ apt-get install apache2 libapache2-mod-wsgi
```
### Copy and modify the VHOST
After `mod_wsgi` is installed, copy the `evennia/web/utils/evennia_wsgi_apache.conf` file to your
apache2 vhosts/sites folder. On Debian/Ubuntu, this is `/etc/apache2/sites-enabled/`. Make your
modifications **after** copying the file there.
Read the comments and change the paths to point to the appropriate locations within your setup.
### Restart/Reload Apache
You'll then want to reload or restart apache2 after changing the configurations.
- *Fedora/RHEL/Ubuntu*
```
$ systemctl restart httpd
```
- *Ubuntu/Debian*
```
$ systemctl restart apache2
```
### Enjoy
With any luck, you'll be able to point your browser at your domain or subdomain that you set up in
your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error
message and work from there. Questions may be directed to our [Evennia Community
site](http://evennia.com).
### A note on code reloading
If your `mod_wsgi` is set up to run on daemon mode (as will be the case by default on Debian and
Ubuntu), you may tell `mod_wsgi` to reload by using the `touch` command on
`evennia/game/web/utils/apache_wsgi.conf`. When `mod_wsgi` sees that the file modification time has
changed, it will force a code reload. Any modifications to the code will not be propagated to the
live instance of your site until reloaded.
If you are not running in daemon mode or want to force the issue, simply restart or reload apache2
to apply your changes.
### Further notes and hints:
If you get strange (and usually uninformative) `Permission denied` errors from Apache, make sure
that your `evennia` directory is located in a place the webserver may actually access. For example,
some Linux distributions may default to very restrictive access permissions on a user's `/home`
directory.
One user commented that they had to add the following to their Apache config to get things to work.
Not confirmed, but worth trying if there are trouble.
<Directory "/home/<yourname>/evennia/game/web">
Options +ExecCGI
Allow from all
</Directory>
## `mod_proxy` and `mod_ssl` setup
Below are steps on running Evennia using a front-end proxy (Apache HTTP), `mod_proxy_http`,
`mod_proxy_wstunnel`, and `mod_ssl`. `mod_proxy_http` and `mod_proxy_wstunnel` will simply be
referred to as
`mod_proxy` below.
### Install `mod_ssl`
- *Fedora/RHEL* - Apache HTTP Server and `mod_ssl` are available in the standard package
repositories for Fedora and RHEL:
```
$ dnf install httpd mod_ssl
or
$ yum install httpd mod_ssl
```
- *Ubuntu/Debian* - Apache HTTP Server and `mod_sslj`kl are installed together in the `apache2`
package and available in the
standard package repositories for Ubuntu and Debian. `mod_ssl` needs to be enabled after
installation:
```
$ apt-get update
$ apt-get install apache2
$ a2enmod ssl
```
### TLS proxy+websocket configuration
Below is a sample configuration for Evennia with a TLS-enabled http and websocket proxy.
#### Apache HTTP Server Configuration
```
<VirtualHost *:80>
# Always redirect to https/443
ServerName mud.example.com
Redirect / https://mud.example.com
</VirtualHost>
<VirtualHost *:443>
ServerName mud.example.com
SSLEngine On
# Location of certificate and key
SSLCertificateFile /etc/pki/tls/certs/mud.example.com.crt
SSLCertificateKeyFile /etc/pki/tls/private/mud.example.com.key
# Use a tool https://www.ssllabs.com/ssltest/ to scan your set after setting up.
SSLProtocol TLSv1.2
SSLCipherSuite HIGH:!eNULL:!NULL:!aNULL
# Proxy all websocket traffic to port 4002 in Evennia
ProxyPass /ws ws://127.0.0.1:4002/
ProxyPassReverse /ws ws://127.0.0.1:4002/
# Proxy all HTTP traffic to port 4001 in Evennia
ProxyPass / http://127.0.0.1:4001/
ProxyPassReverse / http://127.0.0.1:4001/
# Configure separate logging for this Evennia proxy
ErrorLog logs/evennia_error.log
CustomLog logs/evennia_access.log combined
</VirtualHost>
```
#### Evennia secure websocket configuration
There is a slight trick in setting up Evennia so websocket traffic is handled correctly by the
proxy. You must set the `WEBSOCKET_CLIENT_URL` setting in your `mymud/server/conf/settings.py` file:
```
WEBSOCKET_CLIENT_URL = "wss://external.example.com/ws"
```
The setting above is what the client's browser will actually use. Note the use of `wss://` is
because our client will be communicating over an encrypted connection ("wss" indicates websocket
over SSL/TLS). Also, especially note the additional path `/ws` at the end of the URL. This is how
Apache HTTP Server identifies that a particular request should be proxied to Evennia's websocket
port but this should be applicable also to other types of proxies (like nginx).

272
docs/source/Setup/Arxcode-installing-help.md Normal file
View file

@ -0,0 +1,272 @@
# Arxcode installing help
## Introduction
[Arx - After the Reckoning](http://play.arxmush.org/) is a big and very popular
[Evennia](http://www.evennia.com)-based game. Arx is heavily roleplaying-centric, relying on game
masters to drive the story. Technically it's maybe best described as "a MUSH, but with more coded
systems". In August of 2018, the game's developer, Tehom, generously released the [source code of
Arx on github](https://github.com/Arx-Game/arxcode). This is a treasure-trove for developers wanting
to pick ideas or even get a starting game to build on. These instructions are based on the Arx-code
released as of *Aug 12, 2018*.
If you are not familiar with what Evennia is, you can read
[an introduction here](Evennia-Introduction).
It's not too hard to run Arx from the sources (of course you'll start with an empty database) but
since part of Arx has grown organically, it doesn't follow standard Evennia paradigms everywhere.
This page covers one take on installing and setting things up while making your new Arx-based game
better match with the vanilla Evennia install.
## Installing Evennia
Firstly, set aside a folder/directory on your drive for everything to follow.
You need to start by installing [Evennia](http://www.evennia.com) by following most of the [Getting
Started
Instructions](Getting-Started) for your OS. The difference is that you need to `git clone
https://github.com/TehomCD/evennia.git` instead of Evennia's repo because Arx uses TehomCD's older
Evennia 0.8 [fork](https://github.com/TehomCD/evennia), notably still using Python2. This detail is
important if referring to newer Evennia documentation.
If you are new to Evennia it's *highly* recommended that you run through the
instructions in full - including initializing and starting a new empty game and connecting to it.
That way you can be sure Evennia works correctly as a base line. If you have trouble, make sure to
read the [Troubleshooting instructions](Getting-Started#troubleshooting) for your
operating system. You can also drop into our
[forums](https://groups.google.com/forum/#%21forum/evennia), join `#evennia` on `irc.freenode.net`
or chat from the linked [Discord Server](https://discord.gg/NecFePw).
After installing you should have a `virtualenv` running and you should have the following file
structure in your set-aside folder:
```
vienv/
evennia/
mygame/
```
Here `mygame` is the empty game you created during the Evennia install, with `evennia --init`. Go to
that and run `evennia stop` to make sure your empty game is not running. We'll instead let Evenna
run Arx, so in principle you could erase `mygame` - but it could also be good to have a clean game
to compare to.
## Installing Arxcode
### Clone the arxcode repo
Cd to the root of your directory and clone the released source code from github:
git clone https://github.com/Arx-Game/arxcode.git myarx
A new folder `myarx` should appear next to the ones you already had. You could rename this to
something else if you want.
Cd into `myarx`. If you wonder about the structure of the game dir, you can [read more about it
here](Directory-Overview).
### Clean up settings
Arx has split evennia's normal settings into `base_settings.py` and `production_settings.py`. It
also has its own solution for managing 'secret' parts of the settings file. We'll keep most of Arx
way but remove the secret-handling and replace it with the normal Evennia method.
Cd into `myarx/server/conf/` and open the file `settings.py` in a text editor. The top part (within
`"""..."""`) is just help text. Wipe everything underneath that and make it look like this instead
(don't forget to save):
```
from base_settings import *
TELNET_PORTS = [4000]
SERVERNAME = "MyArx"
GAME_SLOGAN = "The cool game"
try:
from server.conf.secret_settings import *
except ImportError:
print("secret_settings.py file not found or failed to import.")
```
> Note: Indents and capitalization matter in Python. Make indents 4 spaces (not tabs) for your own
> sanity. If you want a starter on Python in Evennia, [you can look here](Python-basic-
introduction).
This will import Arx' base settings and override them with the Evennia-default telnet port and give
the game a name. The slogan changes the sub-text shown under the name of your game in the website
header. You can tweak these to your own liking later.
Next, create a new, empty file `secret_settings.py` in the same location as the `settings.py` file.
This can just contain the following:
```python
SECRET_KEY = "sefsefiwwj3 jnwidufhjw4545_oifej whewiu hwejfpoiwjrpw09&4er43233fwefwfw"
```
Replace the long random string with random ASCII characters of your own. The secret key should not
be shared.
Next, open `myarx/server/conf/base_settings.py` in your text editor. We want to remove/comment out
all mentions of the `decouple` package, which Evennia doesn't use (we use `private_settings.py` to
hide away settings that should not be shared).
Comment out `from decouple import config` by adding a `#` to the start of the line: `# from decouple
import config`. Then search for `config(` in the file and comment out all lines where this is used.
Many of these are specific to the server environment where the original Arx runs, so is not that
relevant to us.
### Install Arx dependencies
Arx has some further dependencies beyond vanilla Evennia. Start by `cd`:ing to the root of your
`myarx` folder.
> If you run *Linux* or *Mac*: Edit `myarx/requirements.txt` and comment out the line
> `pypiwin32==219` - it's only needed on Windows and will give an error on other platforms.
Make sure your `virtualenv` is active, then run
pip install -r requirements.txt
The needed Python packages will be installed for you.
### Adding logs/ folder
The Arx repo does not contain the `myarx/server/logs/` folder Evennia expects for storing server
logs. This is simple to add:
# linux/mac
mkdir server/logs
# windows
mkdir server\logs
### Setting up the database and starting
From the `myarx` folder, run
evennia migrate
This creates the database and will step through all database migrations needed.
evennia start
If all goes well Evennia will now start up, running Arx! You can connect to it on `localhost` (or
`127.0.0.1` if your platform doesn't alias `localhost`), port `4000` using a Telnet client.
Alternatively, you can use your web browser to browse to `http://localhost:4001` to see the game's
website and get to the web client.
When you log in you'll get the standard Evennia greeting (since the database is empty), but you can
try `help` to see that it's indeed Arx that is running.
### Additional Setup Steps
The first time you start Evennia after creating the database with the `evennia migrate` step above,
it should create a few starting objects for you - your superuser account, which it will prompt you
to enter, a starting room (Limbo), and a character object for you. If for some reason this does not
occur, you may have to follow the steps below. For the first time Superuser login you may have to
run steps 7-8 and 10 to create and connect to your in-came Character.
1. Login to the game website with your Superuser account.
2. Press the `Admin` button to get into the (Django-) Admin Interface.
3. Navigate to the `Accounts` section.
4. Add a new Account named for the new staffer. Use a place holder password and dummy e-mail
address.
5. Flag account as `Staff` and apply the `Admin` permission group (This assumes you have already set
up an Admin Group in Django).
6. Add Tags named `player` and `developer`.
7. Log into the game using the web client (or a third-party telnet client) using your superuser
account. Move to where you want the new staffer character to appear.
8. In the game client, run `@create/drop <staffername>:typeclasses.characters.Character`, where
`<staffername>` is usually the same name you used for the Staffer account you created in the
Admin earlier (if you are creating a Character for your superuser, use your superuser account
name).
This creates a new in-game Character and places it in your current location.
9. Have the new Admin player log into the game.
10. Have the new Admin puppet the character with `@ic StafferName`.
11. Have the new Admin change their password - `@password <old password> = <new password>`.
Now that you have a Character and an Account object, there's a few additional things you may need to
do in order for some commands to function properly. You can either execute these as in-game commands
while `@ic` (controlling your character object).
1. `@py from web.character.models import RosterEntry;RosterEntry.objects.create(player=self.player,
character=self)`
2. `@py from world.dominion.models import PlayerOrNpc, AssetOwner;dompc =
PlayerOrNpc.objects.create(player = self.player);AssetOwner.objects.create(player=dompc)`
Those steps will give you a 'RosterEntry', 'PlayerOrNpc', and 'AssetOwner' objects. RosterEntry
explicitly connects a character and account object together, even while offline, and contains
additional information about a character's current presence in game (such as which 'roster' they're
in, if you choose to use an active roster of characters). PlayerOrNpc are more character extensions,
as well as support for npcs with no in-game presence and just represented by a name which can be
offscreen members of a character's family. It also allows for membership in Organizations.
AssetOwner holds information about a character or organization's money and resources.
## Alternate guide by Pax for installing on Windows
If for some reason you cannot use the Windows Subsystem for Linux (which would use instructions
identical to the ones above), it's possible to get Evennia running under Anaconda for Windows. The
process is a little bit trickier.
Make sure you have:
* Git for Windows https://git-scm.com/download/win
* Anaconda for Windows https://www.anaconda.com/distribution/
* VC++ Compiler for Python 2.7 http://aka.ms/vcpython27
conda update conda
conda create -n arx python=2.7
source activate arx
Set up a convenient repository place for things.
cd ~
mkdir Source
cd Source
mkdir Arx
cd Arx
Replace the SSH git clone links below with your own github forks.
If you don't plan to change Evennia at all, you can use the
evennia/evennia.git repo instead of a forked one.
git clone git@github.com:<youruser>/evennia.git
git clone git@github.com:<youruser>/arxcode.git
Evennia is a package itself, so we want to install it and all of its
prerequisites, after switching to the appropriately-tagged branch for
Arxcode.
cd evennia
git checkout tags/v0.7 -b arx-master
pip install -e .
Arx has some dependencies of its own, so now we'll go install them
As it is not a package, we'll use the normal requirements file.
cd ../arxcode
pip install -r requirements.txt
The git repo doesn't include the empty log directory and Evennia is unhappy if you
don't have it, so while still in the arxcode directory...
mkdir server/logs
Now hit https://github.com/evennia/evennia/wiki/Arxcode-installing-help and
change the setup stuff as in the 'Clean up settings' section.
Then we will create our default database...
../evennia/bin/windows/evennia.bat migrate
...and do the first run. You need winpty because Windows does not have a TTY/PTY
by default, and so the Python console input commands (used for prompts on first
run) will fail and you will end up in an unhappy place. Future runs, you should
not need winpty.
winpty ../evennia/bin/windows/evennia.bat start
Once this is done, you should have your Evennia server running Arxcode up
on localhost at port 4000, and the webserver at http://localhost:4001/
And you are done! Huzzah!

249
docs/source/Setup/Choosing-An-SQL-Server.md Normal file
View file

@ -0,0 +1,249 @@
# Choosing An SQL Server
This page gives an overview of the supported SQL databases as well as instructions on install:
- SQLite3 (default)
- PostgreSQL
- MySQL / MariaDB
Since Evennia uses [Django](http://djangoproject.com), most of our notes are based off of what we
know from the community and their documentation. While the information below may be useful, you can
always find the most up-to-date and "correct" information at Django's [Notes about supported
Databases](http://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) page.
## SQLite3
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this
database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server
process is needed and the administrative overhead and resource consumption is tiny. It is also very
fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all
that's ever needed.
SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:
* SQLite [ignores length constraints by design](https://www.sqlite.org/faq.html#q9); it is possible
to store very large strings and numbers in fields that technically should not accept them. This is
not something you will notice; your game will read and write them and function normally, but this
*can* create some data migration problems requiring careful thought if you do need to change
databases later.
* SQLite can scale well to storage of millions of objects, but if you end up with a thundering herd
of users trying to access your MUD and web site at the same time, or you find yourself writing long-
running functions to update large numbers of objects on a live game, either will yield errors and
interference. SQLite does not work reliably with multiple concurrent threads or processes accessing
its records. This has to do with file-locking clashes of the database file. So for a production
server making heavy use of process- or thread pools (or when using a third-party webserver like
Apache), a proper database is a more appropriate choice.
### Install of SQlite3
This is installed and configured as part of Evennia. The database file is created as
`mygame/server/evennia.db3` when you run
evennia migrate
without changing any database options. An optional requirement is the `sqlite3` client program -
this is required if you want to inspect the database data manually. A shortcut for using it with the
evennia database is `evennia dbshell`. Linux users should look for the `sqlite3` package for their
distro while Mac/Windows should get the [sqlite-tools package from this
page](https://sqlite.org/download.html).
To inspect the default Evennia database (once it's been created), go to your game dir and do
```bash
sqlite3 server/evennia.db3
# or
evennia dbshell
```
This will bring you into the sqlite command line. Use `.help` for instructions and `.quit` to exit.
See [here](https://gist.github.com/vincent178/10889334) for a cheat-sheet of commands.
## PostgreSQL
[PostgreSQL](https://www.postgresql.org/) is an open-source database engine, recommended by Django.
While not as fast as SQLite for normal usage, it will scale better than SQLite, especially if your
game has an very large database and/or extensive web presence through a separate server process.
### Install and initial setup of PostgreSQL
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily
available for all distributions. You need to also get the `psql` client (this is called `postgresql-
client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql
download page](https://www.postgresql.org/download/). You should be setting up a password for your
database-superuser (always called `postgres`) when you install.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install (`pip
install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
Next, start the postgres client:
```bash
psql -U postgres --password
```
> :warning: **Warning:** With the `--password` argument, Postgres should prompt you for a password.
If it won't, replace that with `-p yourpassword` instead. Do not use the `-p` argument unless you
have to since the resulting command, and your password, will be logged in the shell history.
This will open a console to the postgres service using the psql client.
On the psql command line:
```sql
CREATE USER evennia WITH PASSWORD 'somepassword';
CREATE DATABASE evennia;
-- Postgres-specific optimizations
-- https://docs.djangoproject.com/en/dev/ref/databases/#optimizing-postgresql-s-configuration
ALTER ROLE evennia SET client_encoding TO 'utf8';
ALTER ROLE evennia SET default_transaction_isolation TO 'read committed';
ALTER ROLE evennia SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE evennia TO evennia;
-- Other useful commands:
-- \l (list all databases and permissions)
-- \q (exit)
```
[Here](https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546) is a cheat-sheet for psql commands.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever
you want though). We then grant the 'evennia' user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
`postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above
again to recreate the database and grant privileges.
### Evennia PostgreSQL configuration
Edit `mygame/server/conf/secret_settings.py and add the following section:
```python
#
# PostgreSQL Database Configuration
#
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'evennia',
'USER': 'evennia',
'PASSWORD': 'somepassword',
'HOST': 'localhost',
'PORT': '' # use default
}}
```
If you used some other name for the database and user, enter those instead. Run
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
evennia dbshell
as a shortcut to get into the postgres command line for the right database and user.
With the database setup you should now be able to start start Evennia normally with your new
database.
## MySQL / MariaDB
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics
all functionality and command syntax of the former. So this section covers both.
### Installing and initial setup of MySQL/MariaDB
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
`mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users
will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB
downloads](https://mariadb.org/download/) pages. You also need the respective database clients
(`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.
You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install
mysqlclient`.
Start the database client (this is named the same for both mysql and mariadb):
```bash
mysql -u root -p
```
You should get to enter your database root password (set this up when you installed the database
server).
Inside the database client interface:
```sql
CREATE USER 'evennia'@'localhost' IDENTIFIED BY 'somepassword';
CREATE DATABASE evennia;
ALTER DATABASE `evennia` CHARACTER SET utf8; -- note that it's `evennia` with back-ticks, not
quotes!
GRANT ALL PRIVILEGES ON evennia.* TO 'evennia'@'localhost';
FLUSH PRIVILEGES;
-- use 'exit' to quit client
```
[Here](https://gist.github.com/hofmannsven/9164408) is a mysql command cheat sheet.
Above we created a new local user and database (we called both 'evennia' here, you can name them
what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the
`evennia` database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.
> Note: If you are not using MySQL for anything else you might consider granting the 'evennia' user
full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means
you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.
## Add MySQL configuration to Evennia
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or
`secret_settings.py` if you don't want your db info passed around on git repositories).
> Note: The Django documentation suggests using an external `db.cnf` or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. [issue
#1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in
your settings as below.
```python
#
# MySQL Database Configuration
#
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'evennia',
'USER': 'evennia',
'PASSWORD': 'somepassword',
'HOST': 'localhost', # or an IP Address that your DB is hosted on
'PORT': '', # use default port
}
}
```
Change this to fit your database setup. Next, run:
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
evennia dbshell
as a shortcut to get into the postgres command line for the right database and user.
With the database setup you should now be able to start start Evennia normally with your new
database.
## Others
No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for [MS SQL](http://code.google.com/p/django-mssql/) and possibly a few
others. If you try other databases out, consider expanding this page with instructions.

94
docs/source/Setup/Client-Support-Grid.md Normal file
View file

@ -0,0 +1,94 @@
# Client Support Grid
This grid tries to gather Evennia-specific knowledge about the various clients and protocols used.
Everyone's welcome to report their findings.
##### Legend:
- **Name**: The name of the client. If it's only available for a specific OS, it should be noted
here too.
- **Version**: Which version or range of client versions were tested.
- **Comments**: Any comments or quirks on using this client with Evennia should be added here. Also
note if some other protocol than Telnet is used (like Websockets, SSH etc).
## Client Grid
Name | Version | Comments
:----------:------------
[Evennia webclient][1] | 0.6 | Uses WS/AJAX. [Current client issues][2]
[tintin++][3] | 2.0+ | No MXP support
[tinyfugue][4] | 5.0+ | No UTF-8 support
[MUSHclient][5] (Win) | 4.94 | NAWS reports full text area
[Zmud][6] (Win) | 7.21 | *UNTESTED*
[Cmud][7] (Win) | v3 | *UNTESTED*
[Potato][8] | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand
"localhost", must use `127.0.0.1`. [Newline issue](https://github.com/evennia/evennia/issues/1131).
*Won't send a single blank line on Enter press.
[Mudlet][9] | 3.4+ | No known issues. Some older versions showed <> as html under MXP.
[SimpleMU][10] (Win) | full | *UNTESTED*. Discontinued. NAWS reports pixel size.
[Atlantis][11] (Mac) | 0.9.9.4 | No known issues.
[GMUD][12] | 0.0.1 | Can't handle any telnet handshakes. Not recommended.
[BeipMU][13] (Win) | 3.0.255 | No MXP support. Best to enable "MUD prompt handling", disable
"Handle HTML tags".
[MudRammer][14] (IOS) | 1.8.7 | Bad Telnet Protocol compliance: displays spurious characters.
[MUDMaster][15] (IOS) | 1.3.1 | *UNTESTED*
[BlowTorch][16] (Andr) | 1.1.3 | *Telnet NOP displays as spurious character.
[Mukluk][17] (Andr) | 2015.11.20| *Telnet NOP displays as spurious character. Has UTF-8/Emoji
support.
[Gnome-MUD][18] (Unix) | 0.11.2 | Telnet handshake errors. First (only) attempt at logging in
fails.
[Spyrit][19] | 0.4 | No MXP, OOB support.
[JamochaMUD][20] | 5.2 | Does not support ANSI within MXP text.
[DuckClient][21] (Chrome)| 4.2 | No MXP support. Displays Telnet Go-Ahead and WILL SUPPRESS-GO-AHEAD
as ù character. Also seems to run the `version` command on connection, which will not work in
`MULTISESSION_MODES` above 1.
[KildClient][22] | 2.11.1 | No known issues.
[1]: https://github.com/evennia/evennia/wiki/Web%20features#web-client
[2]: https://github.com/evennia/evennia/issues?utf8=%E2%9C%93&q=client+status%3Dopen+]
[3]: http://tintin.sourceforge.net/
[4]: http://tinyfugue.sourceforge.net/
[5]: http://mushclient.com/
[6]: http://forums.zuggsoft.com/index.php?page=4&action=file&file_id=65
[7]: http://forums.zuggsoft.com/index.php?page=4&action=category&cat_id=11
[8]: http://www.potatomushclient.com/
[9]: http://www.mudlet.org/
[10]: https://archive.org/details/tucows_196173_SimpleMU_MU_Client
[11]: http://www.riverdark.net/atlantis/
[12]: https://sourceforge.net/projects/g-mud/
[13]: http://www.beipmu.com/
[14]: https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072
[15]: https://itunes.apple.com/us/app/mudmaster/id341160033
[16]: http://bt.happygoatstudios.com/
[17]: https://play.google.com/store/apps/details?id=com.crap.mukluk
[18]: https://github.com/GNOME/gnome-mud
[19]: https://spyrit.ierne.eu.org/
[20]: http://jamochamud.org/
[21]: http://duckclient.com/
[22]: https://www.kildclient.org/
## Workarounds for client issues:
### Issue: Telnet NOP displays as spurious character.
Known clients:
* [BlowTorch][16](Andr)
* [Mukluk][17](Andr)
Workaround:
* Set the command in game to `@option NOPKEEPALIVE=off` for the session, or use the `/save`
parameter to disable it for that Evennian account permanently.
* Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client.
### Issue: Won't send blank line on Enter key press.
Known clients:
* [Potato][8]
Workaround:
* Press Control Enter, then Enter key again to send blank line.

71
docs/source/Setup/Evennia-Game-Index.md Normal file
View file

@ -0,0 +1,71 @@
# Evennia Game Index
The [Evennia game index](http://games.evennia.com) is a list of games built or
being built with Evennia. Anyone is allowed to add their game to the index
- also if you have just started development and don't yet accept external
players. It's a chance for us to know you are out there and for you to make us
intrigued about or excited for your upcoming game!
All we ask is that you check so your game-name does not collide with one
already in the list - be nice!
## Connect with the wizard
From your game dir, run
evennia connections
This will start the Evennia _Connection wizard_. From the menu, select to add
your game to the Evennia Game Index. Follow the prompts and don't forget to
save your new settings in the end. Use `quit` at any time if you change your
mind.
> The wizard will create a new file `mygame/server/conf/connection_settings.py`
> with the settings you chose. This is imported from the end of your main
> settings file and will thus override it. You can edit this new file if you
> want, but remember that if you run the wizard again, your changes may get
> over-written.
## Manual Settings
If you don't want to use the wizard (maybe because you already have the client installed from an
earlier version), you can also configure your index entry in your settings file
(`mygame/server/conf/settings.py`). Add the following:
```python
GAME_INDEX_ENABLED = True
GAME_INDEX_LISTING = {
# required
'game_status': 'pre-alpha', # pre-alpha, alpha, beta, launched
'listing_contact': "dummy@dummy.com", # not publicly shown.
'short_description': 'Short blurb',
# optional
'long_description':
"Longer description that can use Markdown like *bold*, _italic_"
"and [linkname](http://link.com). Use \n for line breaks."
'telnet_hostname': 'dummy.com',
'telnet_port': '1234',
'web_client_url': 'dummy.com/webclient',
'game_website': 'dummy.com',
# 'game_name': 'MyGame', # set only if different than settings.SERVERNAME
}
```
Of these, the `game_status`, `short_description` and `listing_contact` are
required. The `listing_contact` is not publicly visible and is only meant as a
last resort if we need to get in touch with you over any listing issue/bug (so
far this has never happened).
If `game_name` is not set, the `settings.SERVERNAME` will be used. Use empty strings
(`''`) for optional fields you don't want to specify at this time.
## Non-public games
If you don't specify neither `telnet_hostname + port` nor
`web_client_url`, the Game index will list your game as _Not yet public_.
Non-public games are moved to the bottom of the index since there is no way
for people to try them out. But it's a good way to show you are out there, even
if you are not ready for players yet.

536
docs/source/Setup/Getting-Started.md Normal file
View file

@ -0,0 +1,536 @@
# Getting Started
This will help you download, install and start Evennia for the first time.
> Note: You don't need to make anything visible to the 'net in order to run and
> test out Evennia. Apart from downloading and updating you don't even need an
> internet connection until you feel ready to share your game with the world.
- [Quick Start](Getting-Started#quick-start)
- [Requirements](Getting-Started#requirements)
- [Linux Install](Getting-Started#linux-install)
- [Mac Install](Getting-Started#mac-install)
- [Windows Install](Getting-Started#windows-install)
- [Running in Docker](Running-Evennia-in-Docker)
- [Where to Go Next](Getting-Started#where-to-go-next)
- [Troubleshooting](Getting-Started#troubleshooting)
- [Glossary of terms](Glossary)
## Quick Start
For the impatient. If you have trouble with a step, you should jump on to the
more detailed instructions for your platform.
1. Install Python, GIT and python-virtualenv. Start a Console/Terminal.
2. `cd` to some place you want to do your development (like a folder
`/home/anna/muddev/` on Linux or a folder in your personal user directory on Windows).
3. `git clone https://github.com/evennia/evennia.git`
4. `virtualenv evenv`
5. `source evenv/bin/activate` (Linux, Mac), `evenv\Scripts\activate` (Windows)
6. `pip install -e evennia`
7. `evennia --init mygame`
8. `cd mygame`
9. `evennia migrate`
10. `evennia start` (make sure to make a superuser when asked)
Evennia should now be running and you can connect to it by pointing a web browser to
`http://localhost:4001` or a MUD telnet client to `localhost:4000` (use `127.0.0.1` if your OS does
not recognize `localhost`).
We also release [Docker images](Running-Evennia-in-Docker)
based on `master` and `develop` branches.
## Requirements
Any system that supports Python3.7+ should work. We'll describe how to install
everything in the following sections.
- Linux/Unix
- Windows (Vista, Win7, Win8, Win10)
- Mac OSX (>=10.5 recommended)
- [Python](http://www.python.org) (v3.7, 3.8 are tested)
- [virtualenv](http://pypi.python.org/pypi/virtualenv) for making isolated
Python environments. Installed with `pip install virtualenv`.
- [GIT](http://git-scm.com/) - version control software for getting and
updating Evennia itself - Mac users can use the
[git-osx-installer](http://code.google.com/p/git-osx-installer/) or the
[MacPorts version](http://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
- [Twisted](http://twistedmatrix.com) (v19.0+)
- [ZopeInterface](http://www.zope.org/Products/ZopeInterface) (v3.0+) - usually included in
Twisted packages
- Linux/Mac users may need the `gcc` and `python-dev` packages or equivalent.
- Windows users need [MS Visual C++](https://aka.ms/vs/16/release/vs_buildtools.exe) and *maybe*
[pypiwin32](https://pypi.python.org/pypi/pypiwin32).
- [Django](http://www.djangoproject.com) (v2.2.x), be warned that latest dev
version is usually untested with Evennia)
## Linux Install
If you run into any issues during the installation and first start, please
check out [Linux Troubleshooting](Getting-Started#linux-troubleshooting).
For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the [dependencies](Getting-Started#requirements):
```
sudo apt-get update
sudo apt-get install python3 python3-pip python3-dev python3-setuptools python3-git
python3-virtualenv gcc
# If you are using an Ubuntu version that defaults to Python3, like 18.04+, use this instead:
sudo apt-get update
sudo apt-get install python3.7 python3-pip python3.7-dev python3-setuptools virtualenv gcc
```
Note that, the default Python version for your distribution may still not be Python3.7 after this.
This is ok - we'll specify exactly which Python to use later.
You should make sure to *not* be `root` after this step, running as `root` is a
security risk. Now create a folder where you want to do all your Evennia
development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on
virtualenv](Glossary#virtualenv).
Run `python -V` to see which version of Python your system defaults to.
```
# If your Linux defaults to Python3.7+:
virtualenv evenv
# If your Linux defaults to Python2 or an older version
# of Python3, you must instead point to Python3.7+ explicitly:
virtualenv -p /usr/bin/python3.7 evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system (or the Linux distro lagging behind
on Python package versions). It will also always use the right version of Python.
Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show that the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
install failed with any issues, see [Linux Troubleshooting](Getting-Started#linux-troubleshooting).
Next we'll start our new game, here called "mygame". This will create yet
another new folder where you will be creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
./muddev
evenv/
evennia/
mygame/
```
You can [configure Evennia](Server-Conf#settings-file) extensively, for example
to use a [different database](Choosing-An-SQL-Server). For now we'll just stick
to the defaults though.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Mac Install
The Evennia server is a terminal program. Open the terminal e.g. from
*Applications->Utilities->Terminal*. [Here is an introduction to the Mac
terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
if you are unsure how it works. If you run into any issues during the
installation, please check out [Mac Troubleshooting](Getting-Started#mac-troubleshooting).
* Python should already be installed but you must make sure it's a high enough version.
([This](http://docs.python-guide.org/en/latest/starting/install/osx/) discusses
how you may upgrade it). Remember that you need Python3.7, not Python2.7!
* GIT can be obtained with
[git-osx-installer](http://code.google.com/p/git-osx-installer/) or via
MacPorts [as described
here](http://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
* If you run into issues with installing `Twisted` later you may need to
install gcc and the Python headers.
After this point you should not need `sudo` or any higher privileges to install anything.
Now create a folder where you want to do all your Evennia development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](Glossary#virtualenv).
Run `python -V` to check which Python your system defaults to.
```
# If your Mac defaults to Python3:
virtualenv evenv
# If your Mac defaults to Python2 you need to specify the Python3.7 binary explicitly:
virtualenv -p /path/to/your/python3.7 evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install --upgrade pip # Old pip versions may be an issue on Mac.
pip install --upgrade setuptools # Ditto concerning Mac issues.
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
install failed with any issues, see [Mac Troubleshooting](Getting-Started#mac-troubleshooting).
Next we'll start our new game. We'll call it "mygame" here. This creates a new
folder where you will be creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
./muddev
evenv/
evennia/
mygame/
```
You can [configure Evennia](Server-Conf#settings-file) extensively, for example
to use a [different database](Choosing-An-SQL-Server). We'll go with the
defaults here.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Windows Install
If you run into any issues during the installation, please check out
[Windows Troubleshooting](Getting-Started#windows-troubleshooting).
> If you are running Windows10, consider using the Windows Subsystem for Linux
> ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead.
> You should then follow the Linux install instructions above.
The Evennia server itself is a command line program. In the Windows launch
menu, start *All Programs -> Accessories -> command prompt* and you will get
the Windows command line interface. Here is [one of many tutorials on using the Windows command
line](http://www.bleepingcomputer.com/tutorials/windows-command-prompt-introduction/)
if you are unfamiliar with it.
* Install Python [from the Python homepage](https://www.python.org/downloads/windows/). You will
need to be a
Windows Administrator to install packages. You want Python version **3.7.0** (latest verified
version), usually
the 64-bit version (although it doesn't matter too much). **When installing, make sure
to check-mark *all* install options, especially the one about making Python
available on the path (you may have to scroll to see it)**. This allows you to
just write `python` in any console without first finding where the `python`
program actually sits on your hard drive.
* You need to also get [GIT](http://git-scm.com/downloads) and install it. You
can use the default install options but when you get asked to "Adjust your PATH
environment", you should select the second option "Use Git from the Windows
Command Prompt", which gives you more freedom as to where you can use the
program.
* Finally you must install the [Microsoft Visual C++ compiler for
Python](https://aka.ms/vs/16/release/vs_buildtools.exe). Download and run the linked installer and
install the C++ tools. Keep all the defaults. Allow the install of the "Win10 SDK", even if you are
on Win7 (not tested on older Windows versions). If you later have issues with installing Evennia due
to a failure to build the "Twisted wheels", this is where you are missing things.
* You *may* need the [pypiwin32](https://pypi.python.org/pypi/pypiwin32) Python headers. Install
these only if you have issues.
You can install Evennia wherever you want. `cd` to that location and create a
new folder for all your Evennia development (let's call it `muddev`).
```
mkdir muddev
cd muddev
```
> Hint: If `cd` isn't working you can use `pushd` instead to force the
> directory change.
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](Glossary#virtualenv).
In your console, try `python -V` to see which version of Python your system
defaults to.
```
pip install virtualenv
# If your setup defaults to Python3.7:
virtualenv evenv
# If your setup defaults to Python2, specify path to python3.exe explicitly:
virtualenv -p C:\Python37\python.exe evenv
# If you get an infinite spooling response, press CTRL + C to interrupt and try using:
python -m venv evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
# If you are using a standard command prompt, you can use the following:
evenv\scripts\activate.bat
# If you are using a PS Shell, Git Bash, or other, you can use the following:
.\evenv\scripts\activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new console window if you want to get access to the Python packages
> (notably the important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia` and `evenv`
folders when you use the `dir` command) and run
```
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](Glossary#pip). If
the install failed with any issues, see [Windows Troubleshooting](Getting-Started#windows-
troubleshooting).
Next we'll start our new game, we'll call it "mygame" here. This creates a new folder where you will
be
creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
path\to\muddev
evenv\
evennia\
mygame\
```
You can [configure Evennia](Server-Conf#settings-file) extensively, for example
to use a [different database](Choosing-An-SQL-Server). We'll go with the
defaults here.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](Getting-Started#where-to-go-next).
## Where to Go Next
Welcome to Evennia! Your new game is fully functioning, but empty. If you just
logged in, stand in the `Limbo` room and run
@batchcommand tutorial_world.build
to build [Evennia's tutorial world](Tutorial-World-Introduction) - it's a small solo quest to
explore. Only run the instructed `@batchcommand` once. You'll get a lot of text scrolling by as the
tutorial is built. Once done, the `tutorial` exit will have appeared out of Limbo - just write
`tutorial` to enter it.
Once you get back to `Limbo` from the tutorial (if you get stuck in the tutorial quest you can do
`@tel #2` to jump to Limbo), a good idea is to learn how to [start, stop and reload](Start-Stop-
Reload) the Evennia server. You may also want to familiarize yourself with some [commonly used terms
in our Glossary](Glossary). After that, why not experiment with [creating some new items and build
some new rooms](Building-Quickstart) out from Limbo.
From here on, you could move on to do one of our [introductory tutorials](Tutorials) or simply dive
headlong into Evennia's comprehensive [manual](https://github.com/evennia/evennia/wiki). While
Evennia has no major game systems out of the box, we do supply a range of optional *contribs* that
you can use or borrow from. They range from dice rolling and alternative color schemes to barter and
combat systems. You can find the [growing list of contribs
here](https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md).
If you have any questions, you can always ask in [the developer
chat](http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb)
`#evennia` on `irc.freenode.net` or by posting to the [Evennia
forums](https://groups.google.com/forum/#%21forum/evennia). You can also join the [Discord
Server](https://discord.gg/NecFePw).
Finally, if you are itching to help out or support Evennia (awesome!) have an
issue to report or a feature to request, [see here](How-To-Get-And-Give-Help).
Enjoy your stay!
## Troubleshooting
If you have issues with installing or starting Evennia for the first time,
check the section for your operating system below. If you have an issue not
covered here, [please report it](https://github.com/evennia/evennia/issues)
so it can be fixed or a workaround found!
Remember, the server logs are in `mygame/server/logs/`. To easily view server logs in the terminal,
you can run `evennia -l`, or (in the future) start the server with `evennia start -l`.
### Linux Troubleshooting
- If you get an error when installing Evennia (especially with lines mentioning
failing to include `Python.h`) then try `sudo apt-get install python3-setuptools python3-dev`.
Once installed, run `pip install -e evennia` again.
- Under some not-updated Linux distributions you may run into errors with a
too-old `setuptools` or missing `functools`. If so, update your environment
with `pip install --upgrade pip wheel setuptools`. Then try `pip install -e evennia` again.
- One user reported a rare issue on Ubuntu 16 is an install error on installing Twisted; `Command
"python setup.py egg_info" failed with error code 1 in /tmp/pip-build-vnIFTg/twisted/` with errors
like `distutils.errors.DistutilsError: Could not find suitable distribution for
Requirement.parse('incremental>=16.10.1')`. This appears possible to solve by simply updating Ubuntu
with `sudo apt-get update && sudo apt-get dist-upgrade`.
- Users of Fedora (notably Fedora 24) has reported a `gcc` error saying the directory
`/usr/lib/rpm/redhat/redhat-hardened-cc1` is missing, despite `gcc` itself being installed. [The
confirmed work-around](https://gist.github.com/yograterol/99c8e123afecc828cb8c) seems to be to
install the `redhat-rpm-config` package with e.g. `sudo dnf install redhat-rpm-config`.
- Some users trying to set up a virtualenv on an NTFS filesystem find that it fails due to issues
with symlinks not being supported. Answer is to not use NTFS (seriously, why would you do that to
yourself?)
### Mac Troubleshooting
- Mac users have reported a critical `MemoryError` when trying to start Evennia on Mac with a Python
version below `2.7.12`. If you get this error, update to the latest XCode and Python2 version.
- Some Mac users have reported not being able to connect to `localhost` (i.e. your own computer). If
so, try to connect to `127.0.0.1` instead, which is the same thing. Use port 4000 from mud clients
and port 4001 from the web browser as usual.
### Windows Troubleshooting
- If you installed Python but the `python` command is not available (even in a new console), then
you might have missed installing Python on the path. In the Windows Python installer you get a list
of options for what to install. Most or all options are pre-checked except this one, and you may
even have to scroll down to see it. Reinstall Python and make sure it's checked.
- If your MUD client cannot connect to `localhost:4000`, try the equivalent `127.0.0.1:4000`
instead. Some MUD clients on Windows does not appear to understand the alias `localhost`.
- If you run `virtualenv evenv` and get a `'virtualenv' is not recognized as an internal or external
command,
operable program or batch file.` error, you can `mkdir evenv`, `cd evenv` and then `python -m
virtualenv .` as a workaround.
- Some Windows users get an error installing the Twisted 'wheel'. A wheel is a pre-compiled binary
package for Python. A common reason for this error is that you are using a 32-bit version of Python,
but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a
slightly older Twisted version. So if, say, version `18.1` failed, install `18.0` manually with `pip
install twisted==18.0`. Alternatively you could try to get a 64-bit version of Python (uninstall the
32bit one). If so, you must then `deactivate` the virtualenv, delete the `evenv` folder and recreate
it anew (it will then use the new Python executable).
- If your server won't start, with no error messages (and no log files at all when starting from
scratch), try to start with `evennia ipstart` instead. If you then see an error about `system cannot
find the path specified`, it may be that the file `evennia/evennia/server/twistd.bat` has the wrong
path to the `twistd` executable. This file is auto-generated, so try to delete it and then run
`evennia start` to rebuild it and see if it works. If it still doesn't work you need to open it in a
text editor like Notepad. It's just one line containing the path to the `twistd.exe` executable as
determined by Evennia. If you installed Twisted in a non-standard location this might be wrong and
you should update the line to the real location.

71
docs/source/Setup/Grapevine.md Normal file
View file

@ -0,0 +1,71 @@
# Grapevine
[Grapevine](http://grapevine.haus) is a new chat network for `MU*`*** games. By
connecting an in-game channel to the grapevine network, players on your game
can chat with players in other games, also non-Evennia ones.
## Configuring Grapevine
To use Grapevine, you first need the `pyopenssl` module. Install it into your
Evennia python environment with
pip install pyopenssl
To configure Grapevine, you'll need to activate it in your settings file.
```python
GRAPEVINE_ENABLED = True
```
Next, register an account at https://grapevine.haus. When you have logged in,
go to your Settings/Profile and to the `Games` sub menu. Here you register your
new game by filling in its information. At the end of registration you are going
to get a `Client ID` and a `Client Secret`. These should not be shared.
Open/create the file `mygame/server/conf/secret_settings.py` and add the following:
```python
GRAPEVINE_CLIENT_ID = "<client ID>"
GRAPEVINE_CLIENT_SECRET = "<client_secret>"
```
You can also customize the Grapevine channels you are allowed to connect to. This
is added to the `GRAPEVINE_CHANNELS` setting. You can see which channels are available
by going to the Grapevine online chat here: https://grapevine.haus/chat.
Start/reload Evennia and log in as a privileged user. You should now have a new
command available: `@grapevine2chan`. This command is called like this:
@grapevine2chan[/switches] <evennia_channel> = <grapevine_channel>
Here, the `evennia_channel` must be the name of an existing Evennia channel and
`grapevine_channel` one of the supported channels in `GRAPEVINE_CHANNELS`.
> At the time of writing, the Grapevine network only has two channels:
> `testing` and `gossip`. Evennia defaults to allowing connecting to both. Use
> `testing` for trying your connection.
## Setting up Grapevine, step by step
You can connect Grapevine to any Evennia channel (so you could connect it to
the default *public* channel if you like), but for testing, let's set up a
new channel `gw`.
@ccreate gw = This is connected to an gw channel!
You will automatically join the new channel.
Next we will create a connection to the Grapevine network.
@grapevine2chan gw = gossip
Evennia will now create a new connection and connect it to Grapevine. Connect
to https://grapevine.haus/chat to check.
Write something in the Evennia channel *gw* and check so a message appears in
the Grapevine chat. Write a reply in the chat and the grapevine bot should echo
it to your channel in-game.
Your Evennia gamers can now chat with users on external Grapevine channels!

61
docs/source/Setup/HAProxy-Config-(Optional).md Normal file
View file

@ -0,0 +1,61 @@
# HAProxy Config (Optional)
### Evennia, HTTPS and Secure Websockets can play nicely together, quickly.
May I suggest giving HAProxy 1.5+ a chance...
Installing HAProxy is usually as simple as:
```
# Redhat derivatives
yum install haproxy
# dnf instead of yum for very recent Fedora distros.
```
or
```
# Debian derivatives
apt install haproxy
```
Configuration of HAProxy requires a single file given as an argument on the command line:
```
haproxy -f /path/to/config.file
```
In it (example using haproxy 1.5.18 on Centos7):
```
# stuff provided by the default haproxy installs
global
log /dev/log local0
chroot /var/lib/haproxy
maxconn 4000
user haproxy
defaults
mode http
option forwardfor
# Evennia Specifics
listen evennia-https-website
bind <public-ip-address>:<public-SSL-port--probably-443> ssl no-sslv3 no-tlsv10 crt
/path/to/your-cert.pem
server localhost 127.0.0.1:<evennia-web-port-probably-4001>
listen evennia-secure-websocket
bind <public-ip-address>:<WEBSOCKET_CLIENT_URL 4002> ssl no-sslv3 no-tlsv10 crt /path/to/your-
cert.pem
server localhost 127.0.0.1:<WEBSOCKET_CLIENT_URL 4002>
timeout client 10m
timeout server 10m
```
Then edit mygame/server/conf/settings.py and add:
```
WEBSERVER_INTERFACES = ['127.0.0.1']
WEBSOCKET_CLIENT_INTERFACE = '127.0.0.1'
```
or
```
LOCKDOWN_MODE=True
```
and
```
WEBSOCKET_CLIENT_URL="wss://yourhost.com:4002/"
```

110
docs/source/Setup/How-to-connect-Evennia-to-Twitter.md Normal file
View file

@ -0,0 +1,110 @@
# How to connect Evennia to Twitter
[Twitter](http://en.wikipedia.org/wiki/twitter) is an online social networking service that enables
users to send and read short 280-character messages called "tweets". Following is a short tutorial
explaining how to enable users to send tweets from inside Evennia.
## Configuring Twitter
You must first have a Twitter account. Log in and register an App at the [Twitter Dev
Site](https://apps.twitter.com/). Make sure you enable access to "write" tweets!
To tweet from Evennia you will need both the "API Token" and the "API secret" strings as well as the
"Access Token" and "Access Secret" strings.
Twitter changed their requirements to require a Mobile number on the Twitter account to register new
apps with write access. If you're unable to do this, please see [this Dev
post](https://dev.twitter.com/notifications/new-apps-registration) which describes how to get around
it.
## Install the twitter python module
To use Twitter you must install the [Twitter](https://pypi.python.org/pypi/twitter) Python module:
```
pip install python-twitter
```
## A basic tweet command
Evennia doesn't have a `tweet` command out of the box so you need to write your own little
[Command](Commands) in order to tweet. If you are unsure about how commands work and how to add
them, it can be an idea to go through the [Adding a Command Tutorial](Adding-Command-Tutorial)
before continuing.
You can create the command in a separate command module (something like `mygame/commands/tweet.py`)
or together with your other custom commands, as you prefer.
This is how it can look:
```python
import twitter
from evennia import Command
# here you insert your unique App tokens
# from the Twitter dev site
TWITTER_API = twitter.Api(consumer_key='api_key',
consumer_secret='api_secret',
access_token_key='access_token_key',
access_token_secret='access_token_secret')
class CmdTweet(Command):
"""
Tweet a message
Usage:
tweet <message>
This will send a Twitter tweet to a pre-configured Twitter account.
A tweet has a maximum length of 280 characters.
"""
key = "tweet"
locks = "cmd:pperm(tweet) or pperm(Developers)"
help_category = "Comms"
def func(self):
"This performs the tweet"
caller = self.caller
tweet = self.args
if not tweet:
caller.msg("Usage: tweet <message>")
return
tlen = len(tweet)
if tlen > 280:
caller.msg("Your tweet was %i chars long (max 280)." % tlen)
return
# post the tweet
TWITTER_API.PostUpdate(tweet)
caller.msg("You tweeted:\n%s" % tweet)
```
Be sure to substitute your own actual API/Access keys and secrets in the appropriate places.
We default to limiting tweet access to players with `Developers`-level access *or* to those players
that have the permission "tweet" (allow individual characters to tweet with `@perm/player playername
= tweet`). You may change the [lock](Locks) as you feel is appropriate. Change the overall
permission to `Players` if you want everyone to be able to tweet.
Now add this command to your default command set (e.g in `mygame/commands/defalt_cmdsets.py`") and
reload the server. From now on those with access can simply use `tweet <message>` to see the tweet
posted from the game's Twitter account.
## Next Steps
This shows only a basic tweet setup, other things to do could be:
* Auto-Adding the character name to the tweet
* More error-checking of postings
* Changing locks to make tweeting open to more people
* Echo your tweets to an in-game channel
Rather than using an explicit command you can set up a Script to send automatic tweets, for example
to post updated game stats. See the [Tweeting Game Stats tutorial](Tutorial-Tweeting-Game-Stats) for
help.

90
docs/source/Setup/IRC.md Normal file
View file

@ -0,0 +1,90 @@
# IRC
_Disambiguation: This page is related to using IRC inside an Evennia game. To join the official
Evennia IRC chat, connect to irc.freenode.net and join #evennia. Alternatively, you can [join our
Discord](https://discord.gg/NecFePw), which is mirrored to IRC._
[IRC (Internet Relay Chat)](http://en.wikipedia.org/wiki/Internet_Relay_Chat) is a long standing
chat protocol used by many open-source projects for communicating in real time. By connecting one of
Evennia's [Channels](Communications) to an IRC channel you can communicate also with people not on
an mud themselves. You can also use IRC if you are only running your Evennia MUD locally on your
computer (your game doesn't need to be open to the public)! All you need is an internet connection.
For IRC operation you also need [twisted.words](http://twistedmatrix.com/trac/wiki/TwistedWords).
This is available simply as a package *python-twisted-words* in many Linux distros, or directly
downloadable from the link.
## Configuring IRC
To configure IRC, you'll need to activate it in your settings file.
```python
IRC_ENABLED = True
```
Start Evennia and log in as a privileged user. You should now have a new command available:
`@irc2chan`. This command is called like this:
@irc2chan[/switches] <evennia_channel> = <ircnetwork> <port> <#irchannel> <botname>
If you already know how IRC works, this should be pretty self-evident to use. Read the help entry
for more features.
## Setting up IRC, step by step
You can connect IRC to any Evennia channel (so you could connect it to the default *public* channel
if you like), but for testing, let's set up a new channel `irc`.
@ccreate irc = This is connected to an irc channel!
You will automatically join the new channel.
Next we will create a connection to an external IRC network and channel. There are many, many IRC
nets. [Here is a list](http://www.irchelp.org/irchelp/networks/popular.html) of some of the biggest
ones, the one you choose is not really very important unless you want to connect to a particular
channel (also make sure that the network allows for "bots" to connect).
For testing, we choose the *Freenode* network, `irc.freenode.net`. We will connect to a test
channel, let's call it *#myevennia-test* (an IRC channel always begins with `#`). It's best if you
pick an obscure channel name that didn't exist previously - if it didn't exist it will be created
for you.
> *Don't* connect to `#evennia` for testing and debugging, that is Evennia's official chat channel!
You *are* welcome to connect your game to `#evennia` once you have everything working though - it
can be a good way to get help and ideas. But if you do, please do so with an in-game channel open
only to your game admins and developers).
The *port* needed depends on the network. For Freenode this is `6667`.
What will happen is that your Evennia server will connect to this IRC channel as a normal user. This
"user" (or "bot") needs a name, which you must also supply. Let's call it "mud-bot".
To test that the bot connects correctly you also want to log onto this channel with a separate,
third-party IRC client. There are hundreds of such clients available. If you use Firefox, the
*Chatzilla* plugin is good and easy. Freenode also offers its own web-based chat page. Once you
have connected to a network, the command to join is usually `/join #channelname` (don't forget the
#).
Next we connect Evennia with the IRC channel.
@irc2chan irc = irc.freenode.net 6667 #myevennia-test mud-bot
Evennia will now create a new IRC bot `mud-bot` and connect it to the IRC network and the channel
#myevennia. If you are connected to the IRC channel you will soon see the user *mud-bot* connect.
Write something in the Evennia channel *irc*.
irc Hello, World!
[irc] Anna: Hello, World!
If you are viewing your IRC channel with a separate IRC client you should see your text appearing
there, spoken by the bot:
mud-bot> [irc] Anna: Hello, World!
Write `Hello!` in your IRC client window and it will appear in your normal channel, marked with the
name of the IRC channel you used (#evennia here).
[irc] Anna@#myevennia-test: Hello!
Your Evennia gamers can now chat with users on external IRC channels!

143
docs/source/Setup/Installing-on-Android.md Normal file
View file

@ -0,0 +1,143 @@
# Installing on Android
This page describes how to install and run the Evennia server on an Android phone. This will involve
installing a slew of third-party programs from the Google Play store, so make sure you are okay with
this before starting.
## Install Termux
The first thing to do is install a terminal emulator that allows a "full" version of linux to be
run. Note that Android is essentially running on top of linux so if you have a rooted phone, you may
be able to skip this step. You *don't* require a rooted phone to install Evennia though.
Assuming we do not have root, we will install
[Termux](https://play.google.com/store/apps/details?id=com.termux&hl=en).
Termux provides a base installation of Linux essentials, including apt and Python, and makes them
available under a writeable directory. It also gives us a terminal where we can enter commands. By
default, Android doesn't give you permissions to the root folder, so Termux pretends that its own
installation directory is the root directory.
Termux will set up a base system for us on first launch, but we will need to install some
prerequisites for Evennia. Commands you should run in Termux will look like this:
```
$ cat file.txt
```
The `$` symbol is your prompt - do not include it when running commands.
## Prerequisites
To install some of the libraries Evennia requires, namely Pillow and Twisted, we have to first
install some packages they depend on. In Termux, run the following
```
$ pkg install -y clang git zlib ndk-sysroot libjpeg-turbo libcrypt python
```
Termux ships with Python 3, perfect. Python 3 has venv (virtualenv) and pip (Python's module
installer) built-in.
So, let's set up our virtualenv. This keeps the Python packages we install separate from the system
versions.
```
$ cd
$ python3 -m venv evenv
```
This will create a new folder, called `evenv`, containing the new python executable.
Next, let's activate our new virtualenv. Every time you want to work on Evennia, you need to run the
following command:
```
$ source evenv/bin/activate
```
Your prompt will change to look like this:
```
(evenv) $
```
Update the updaters and installers in the venv: pip, setuptools and wheel.
```
python3 -m pip install --upgrade pip setuptools wheel
```
### Installing Evennia
Now that we have everything in place, we're ready to download and install Evennia itself.
Mysterious incantations
```
export LDFLAGS="-L/data/data/com.termux/files/usr/lib/"
export CFLAGS="-I/data/data/com.termux/files/usr/include/"
```
(these tell clang, the C compiler, where to find the bits for zlib when building Pillow)
Install the latest Evennia in a way that lets you edit the source
```
(evenv) $ pip install --upgrade -e 'git+https://github.com/evennia/evennia#egg=evennia'
```
This step will possibly take quite a while - we are downloading Evennia and are then installing it,
building all of the requirements for Evennia to run. If you run into trouble on this step, please
see [Troubleshooting](Installing-on-Android#troubleshooting).
You can go to the dir where Evennia is installed with `cd $VIRTUAL_ENV/src/evennia`. `git grep
(something)` can be handy, as can `git diff`
### Final steps
At this point, Evennia is installed on your phone! You can now continue with the original [Getting
Started](Getting-Started) instruction, we repeat them here for clarity.
To start a new game:
```
(evenv) $ evennia --init mygame
(evenv) $ ls
mygame evenv
```
To start the game for the first time:
```
(evenv) $ cd mygame
(evenv) $ evennia migrate
(evenv) $ evennia start
```
Your game should now be running! Open a web browser at http://localhost:4001 or point a telnet
client to localhost:4000 and log in with the user you created.
## Running Evennia
When you wish to run Evennia, get into your Termux console and make sure you have activated your
virtualenv as well as are in your game's directory. You can then run evennia start as normal.
```
$ cd ~ && source evenv/bin/activate
(evenv) $ cd mygame
(evenv) $ evennia start
```
You may wish to look at the [Linux Instructions](Getting-Started#linux-install) for more.
## Caveats
- Android's os module doesn't support certain functions - in particular getloadavg. Thusly, running
the command @server in-game will throw an exception. So far, there is no fix for this problem.
- As you might expect, performance is not amazing.
- Android is fairly aggressive about memory handling, and you may find that your server process is
killed if your phone is heavily taxed. Termux seems to keep a notification up to discourage this.
## Troubleshooting
As time goes by and errors are reported, this section will be added to.
Some steps to try anyway:
* Make sure your packages are up-to-date, try running `pkg update && pkg upgrade -y`
* Make sure you've installed the clang package. If not, try `pkg install clang -y`
* Make sure you're in the right directory. `cd ~/mygame
* Make sure you've sourced your virtualenv. type `cd && source evenv/bin/activate`
* See if a shell will start: `cd ~/mygame ; evennia shell`
* Look at the log files in ~/mygame/server/logs/

431
docs/source/Setup/Online-Setup.md Normal file
View file

@ -0,0 +1,431 @@
# Online Setup
Evennia development can be made without any Internet connection beyond fetching updates. At some
point however, you are likely to want to make your game visible online, either as part opening it to
the public or to allow other developers or beta testers access to it.
## Connecting from the outside
Accessing your Evennia server from the outside is not hard on its own. Any issues are usually due to
the various security measures your computer, network or hosting service has. These will generally
(and correctly) block outside access to servers on your machine unless you tell them otherwise.
We will start by showing how to host your server on your own local computer. Even if you plan to
host your "real" game on a remote host later, setting it up locally is useful practice. We cover
remote hosting later in this document.
Out of the box, Evennia uses three ports for outward communication. If your computer has a firewall,
these should be open for in/out communication (and only these, other ports used by Evennia are
internal to your computer only).
- `4000`, telnet, for traditional mud clients
- `4001`, HTTP for the website)
- `4002`, websocket, for the web client
Evennia will by default accept incoming connections on all interfaces (`0.0.0.0`) so in principle
anyone knowing the ports to use and has the IP address to your machine should be able to connect to
your game.
- Make sure Evennia is installed and that you have activated the virtualenv. Start the server with
`evennia start --log`. The `--log` (or `-l`) will make sure that the logs are echoed to the
terminal.
> Note: If you need to close the log-view, use `Ctrl-C`. Use just `evennia --log` on its own to
start tailing the logs again.
- Make sure you can connect with your web browser to `http://localhost:4001` or, alternatively,
`http:127.0.0.1:4001` which is the same thing. You should get your Evennia web site and be able to
play the game in the web client. Also check so that you can connect with a mud client to host
`localhost`, port `4000` or host `127.0.0.1`, port `4000`.
- [Google for "my ip"](https://www.google.se/search?q=my+ip) or use any online service to figure out
what your "outward-facing" IP address is. For our purposes, let's say your outward-facing IP is
`203.0.113.0`.
- Next try your outward-facing IP by opening `http://203.0.113.0:4001` in a browser. If this works,
that's it! Also try telnet, with the server set to `203.0.113.0` and port `4000`. However, most
likely it will *not* work. If so, read on.
- If your computer has a firewall, it may be blocking the ports we need (it may also block telnet
overall). If so, you need to open the outward-facing ports to in/out communication. See the
manual/instructions for your firewall software on how to do this. To test you could also temporarily
turn off your firewall entirely to see if that was indeed the problem.
- Another common problem for not being able to connect is that you are using a hardware router
(like a wifi router). The router sits 'between' your computer and the Internet. So the IP you find
with Google is the *router's* IP, not that of your computer. To resolve this you need to configure
your router to *forward* data it gets on its ports to the IP and ports of your computer sitting in
your private network. How to do this depends on the make of your router; you usually configure it
using a normal web browser. In the router interface, look for "Port forwarding" or maybe "Virtual
server". If that doesn't work, try to temporarily wire your computer directly to the Internet outlet
(assuming your computer has the ports for it). You'll need to check for your IP again. If that
works, you know the problem is the router.
> Note: If you need to reconfigure a router, the router's Internet-facing ports do *not* have to
have to have the same numbers as your computer's (and Evennia's) ports! For example, you might want
to connect Evennia's outgoing port 4001 to an outgoing router port 80 - this is the port HTTP
requests use and web browsers automatically look for - if you do that you could go to
`http://203.0.113.0` without having to add the port at the end. This would collide with any other
web services you are running through this router though.
### Settings example
You can connect Evennia to the Internet without any changes to your settings. The default settings
are easy to use but are not necessarily the safest. You can customize your online presence in your
[settings file](Server-Conf#settings-file). To have Evennia recognize changed port settings you have
to do a full `evennia reboot` to also restart the Portal and not just the Server component.
Below is an example of a simple set of settings, mostly using the defaults. Evennia will require
access to five computer ports, of which three (only) should be open to the outside world. Below we
continue to assume that our server address is `203.0.113.0`.
```python
# in mygame/server/conf/settings.py
SERVERNAME = "MyGame"
# open to the internet: 4000, 4001, 4002
# closed to the internet (internal use): 4005, 4006
TELNET_PORTS = [4000]
WEBSOCKET_CLIENT_PORT = 4002
WEBSERVER_PORTS = [(4001, 4005)]
AMP_PORT = 4006
# Optional - security measures limiting interface access
# (don't set these before you know things work without them)
TELNET_INTERFACES = ['203.0.113.0']
WEBSOCKET_CLIENT_INTERFACE = '203.0.113.0'
ALLOWED_HOSTS = [".mymudgame.com"]
# uncomment if you want to lock the server down for maintenance.
# LOCKDOWN_MODE = True
```
Read on for a description of the individual settings.
### Telnet
```python
# Required. Change to whichever outgoing Telnet port(s)
# you are allowed to use on your host.
TELNET_PORTS = [4000]
# Optional for security. Restrict which telnet
# interfaces we should accept. Should be set to your
# outward-facing IP address(es). Default is ´0.0.0.0´
# which accepts all interfaces.
TELNET_INTERFACES = ['0.0.0.0']
```
The `TELNET_*` settings are the most important ones for getting a traditional base game going. Which
IP addresses you have available depends on your server hosting solution (see the next sections).
Some hosts will restrict which ports you are allowed you use so make sure to check.
### Web server
```python
# Required. This is a list of tuples
# (outgoing_port, internal_port). Only the outgoing
# port should be open to the world!
# set outgoing port to 80 if you want to run Evennia
# as the only web server on your machine (if available).
WEBSERVER_PORTS = [(4001, 4005)]
# Optional for security. Change this to the IP your
# server can be reached at (normally the same
# as TELNET_INTERFACES)
WEBSERVER_INTERFACES = ['0.0.0.0']
# Optional for security. Protects against
# man-in-the-middle attacks. Change it to your server's
# IP address or URL when you run a production server.
ALLOWED_HOSTS = ['*']
```
The web server is always configured with two ports at a time. The *outgoing* port (`4001` by
default) is the port external connections can use. If you don't want users to have to specify the
port when they connect, you should set this to `80` - this however only works if you are not running
any other web server on the machine.
The *internal* port (`4005` by default) is used internally by Evennia to communicate between the
Server and the Portal. It should not be available to the outside world. You usually only need to
change the outgoing port unless the default internal port is clashing with some other program.
### Web client
```python
# Required. Change this to the main IP address of your server.
WEBSOCKET_CLIENT_INTERFACE = '0.0.0.0'
# Optional and needed only if using a proxy or similar. Change
# to the IP or address where the client can reach
# your server. The ws:// part is then required. If not given, the client
# will use its host location.
WEBSOCKET_CLIENT_URL = ""
# Required. Change to a free port for the websocket client to reach
# the server on. This will be automatically appended
# to WEBSOCKET_CLIENT_URL by the web client.
WEBSOCKET_CLIENT_PORT = 4002
```
The websocket-based web client needs to be able to call back to the server, and these settings must
be changed for it to find where to look. If it cannot find the server you will get an warning in
your browser's Console (in the dev tools of the browser), and the client will revert to the AJAX-
based of the client instead, which tends to be slower.
### Other ports
```python
# Optional public facing. Only allows SSL connections (off by default).
SSL_PORTS = [4003]
SSL_INTERFACES = ['0.0.0.0']
# Optional public facing. Only if you allow SSH connections (off by default).
SSH_PORTS = [4004]
SSH_INTERFACES = ['0.0.0.0']
# Required private. You should only change this if there is a clash
# with other services on your host. Should NOT be open to the
# outside world.
AMP_PORT = 4006
```
The `AMP_PORT` is required to work, since this is the internal port linking Evennia's [Server and
Portal](Portal-And-Server) components together. The other ports are encrypted ports that may be
useful for custom protocols but are otherwise not used.
### Lockdown mode
When you test things out and check configurations you may not want players to drop in on you.
Similarly, if you are doing maintenance on a live game you may want to take it offline for a while
to fix eventual problems without risking people connecting. To do this, stop the server with
`evennia stop` and add `LOCKDOWN_MODE = True` to your settings file. When you start the server
again, your game will only be accessible from localhost.
### Registering with the Evennia game directory
Once your game is online you should make sure to register it with the [Evennia Game
Index](http://games.evennia.com/). Registering with the index will help people find your server,
drum up interest for your game and also shows people that Evennia is being used. You can do this
even if you are just starting development - if you don't give any telnet/web address it will appear
as _Not yet public_ and just be a teaser. If so, pick _pre-alpha_ as the development status.
To register, stand in your game dir, run
evennia connections
and follow the instructions. See the [Game index page](Evennia-Game-Index) for more details.
## SSL
SSL can be very useful for web clients. It will protect the credentials and gameplay of your users
over a web client if they are in a public place, and your websocket can also be switched to WSS for
the same benefit. SSL certificates used to cost money on a yearly basis, but there is now a program
that issues them for free with assisted setup to make the entire process less painful.
Options that may be useful in combination with an SSL proxy:
```
# See above for the section on Lockdown Mode.
# Useful for a proxy on the public interface connecting to Evennia on localhost.
LOCKDOWN_MODE = True
# Have clients communicate via wss after connecting with https to port 4001.
# Without this, you may get DOMException errors when the browser tries
# to create an insecure websocket from a secure webpage.
WEBSOCKET_CLIENT_URL = "wss://fqdn:4002"
```
### Let's Encrypt
[Let's Encrypt](https://letsencrypt.org) is a certificate authority offering free certificates to
secure a website with HTTPS. To get started issuing a certificate for your web server using Let's
Encrypt, see these links:
- [Let's Encrypt - Getting Started](https://letsencrypt.org/getting-started/)
- The [CertBot Client](https://certbot.eff.org/) is a program for automatically obtaining a
certificate, use it and maintain it with your website.
Also, on Freenode visit the #letsencrypt channel for assistance from the community. For an
additional resource, Let's Encrypt has a very active [community
forum](https://community.letsencrypt.org/).
[A blog where someone sets up Let's Encrypt](https://www.digitalocean.com/community/tutorials/how-
to-secure-apache-with-let-s-encrypt-on-ubuntu-16-04)
The only process missing from all of the above documentation is how to pass verification. This is
how Let's Encrypt verifies that you have control over your domain (not necessarily ownership, it's
Domain Validation (DV)). This can be done either with configuring a certain path on your web server
or through a TXT record in your DNS. Which one you will want to do is a personal preference, but can
also be based on your hosting choice. In a controlled/cPanel environment, you will most likely have
to use DNS verification.
## Relevant SSL Proxy Setup Information
- [Apache webserver configuration](Apache-Config) (optional)
- [HAProxy Config](HAProxy-Config-(Optional))
## Hosting locally or remotely?
### Using your own computer as a server
What we showed above is by far the simplest and probably cheapest option: Run Evennia on your own
home computer. Moreover, since Evennia is its own web server, you don't need to install anything
extra to have a website.
**Advantages**
- Free (except for internet costs and the electrical bill).
- Full control over the server and hardware (it sits right there!).
- Easy to set up.
- Suitable for quick setups - e.g. to briefly show off results to your collaborators.
**Disadvantages**
- You need a good internet connection, ideally without any upload/download limits/costs.
- If you want to run a full game this way, your computer needs to always be on. It could be noisy,
and as mentioned, the electrical bill must be considered.
- No support or safety - if your house burns down, so will your game. Also, you are yourself
responsible for doing regular backups.
- Potentially not as easy if you don't know how to open ports in your firewall or router.
- Home IP numbers are often dynamically allocated, so for permanent online time you need to set up a
DNS to always re-point to the right place (see below).
- You are personally responsible for any use/misuse of your internet connection-- though unlikely
(but not impossible) if running your server somehow causes issues for other customers on the
network, goes against your ISP's terms of service (many ISPs insist on upselling you to a business-
tier connection) or you are the subject of legal action by a copyright holder, you may find your
main internet connection terminated as a consequence.
#### Setting up your own machine as a server
[The first section](Online-Setup#connecting-from-the-outside) of this page describes how to do this
and allow users to connect to the IP address of your machine/router.
A complication with using a specific IP address like this is that your home IP might not remain the
same. Many ISPs (Internet Service Providers) allocates a *dynamic* IP to you which could change at
any time. When that happens, that IP you told people to go to will be worthless. Also, that long
string of numbers is not very pretty, is it? It's hard to remember and not easy to use in marketing
your game. What you need is to alias it to a more sensible domain name - an alias that follows you
around also when the IP changes.
1. To set up a domain name alias, we recommend starting with a free domain name from
[FreeDNS](http://freedns.afraid.org/). Once you register there (it's free) you have access to tens
of thousands domain names that people have "donated" to allow you to use for your own sub domain.
For example, `strangled.net` is one of those available domains. So tying our IP address to
`strangled.net` using the subdomain `evennia` would mean that one could henceforth direct people to
`http://evennia.strangled.net:4001` for their gaming needs - far easier to remember!
1. So how do we make this new, nice domain name follow us also if our IP changes? For this we need
to set up a little program on our computer. It will check whenever our ISP decides to change our IP
and tell FreeDNS that. There are many alternatives to be found from FreeDNS:s homepage, one that
works on multiple platforms is [inadyn](http://www.inatech.eu/inadyn/). Get it from their page or,
in Linux, through something like `apt-get install inadyn`.
1. Next, you login to your account on FreeDNS and go to the
[Dynamic](http://freedns.afraid.org/dynamic/) page. You should have a list of your subdomains. Click
the `Direct URL` link and you'll get a page with a text message. Ignore that and look at the URL of
the page. It should be ending in a lot of random letters. Everything after the question mark is your
unique "hash". Copy this string.
1. You now start inadyn with the following command (Linux):
`inadyn --dyndns_system default@freedns.afraid.org -a <my.domain>,<hash> &`
where `<my.domain>` would be `evennia.strangled.net` and `<hash>` the string of numbers we copied
from FreeDNS. The `&` means we run in the background (might not be valid in other operating
systems). `inadyn` will henceforth check for changes every 60 seconds. You should put the `inadyn`
command string in a startup script somewhere so it kicks into gear whenever your computer starts.
### Remote hosting
Your normal "web hotel" will probably not be enough to run Evennia. A web hotel is normally aimed at
a very specific usage - delivering web pages, at the most with some dynamic content. The "Python
scripts" they refer to on their home pages are usually only intended to be CGI-like scripts launched
by their webserver. Even if they allow you shell access (so you can install the Evennia dependencies
in the first place), resource usage will likely be very restricted. Running a full-fledged game
server like Evennia will probably be shunned upon or be outright impossible. If you are unsure,
contact your web hotel and ask about their policy on you running third-party servers that will want
to open custom ports.
The options you probably need to look for are *shell account services*, *VPS:es* or *Cloud
services*. A "Shell account" service means that you get a shell account on a server and can log in
like any normal user. By contrast, a *VPS* (Virtual Private Server) service usually means that you
get `root` access, but in a virtual machine. There are also *Cloud*-type services which allows for
starting up multiple virtual machines and pay for what resources you use.
**Advantages**
- Shell accounts/VPS/clouds offer more flexibility than your average web hotel - it's the ability to
log onto a shared computer away from home.
- Usually runs a Linux flavor, making it easy to install Evennia.
- Support. You don't need to maintain the server hardware. If your house burns down, at least your
game stays online. Many services guarantee a certain level of up-time and also do regular backups
for you. Make sure to check, some offer lower rates in exchange for you yourself being fully
responsible for your data/backups.
- Usually offers a fixed domain name, so no need to mess with IP addresses.
- May have the ability to easily deploy [docker](Running-Evennia-in-Docker) versions of evennia
and/or your game.
**Disadvantages**
- Might be pretty expensive (more so than a web hotel). Note that Evennia will normally need at
least 100MB RAM and likely much more for a large production game.
- Linux flavors might feel unfamiliar to users not used to ssh/PuTTy and the Linux command line.
- You are probably sharing the server with many others, so you are not completely in charge. CPU
usage might be limited. Also, if the server people decides to take the server down for maintenance,
you have no choice but to sit it out (but you'll hopefully be warned ahead of time).
#### Installing Evennia on a remote server
Firstly, if you are familiar with server infrastructure, consider using [Docker](Running-Evennia-in-
Docker) to deploy your game to the remote server; it will likely ease installation and deployment.
Docker images may be a little confusing if you are completely new to them though.
If not using docker, and assuming you know how to connect to your account over ssh/PuTTy, you should
be able to follow the [Getting Started](Getting-Started) instructions normally. You only need Python
and GIT pre-installed; these should both be available on any servers (if not you should be able to
easily ask for them to be installed). On a VPS or Cloud service you can install them yourself as
needed.
If `virtualenv` is not available and you can't get it, you can download it (it's just a single file)
from [the virtualenv pypi](https://pypi.python.org/pypi/virtualenv). Using `virtualenv` you can
install everything without actually needing to have further `root` access. Ports might be an issue,
so make sure you know which ports are available to use and reconfigure Evennia accordingly.
### Hosting options
To find commercial solutions, browse the web for "shell access", "VPS" or "Cloud services" in your
region. You may find useful offers for "low cost" VPS hosting on [Low End Box][7]. The associated
[Low End Talk][8] forum can be useful for health checking the many small businesses that offer
"value" hosting, and occasionally for technical suggestions.
There are all sorts of services available. Below are some international suggestions offered by
Evennia users:
Hosting name | Type | Lowest price | Comments
:--------------:|:-------:---------------
[silvren.com][1] | Shell account | Free for MU* | Private hobby provider so don't assume backups
or expect immediate support. To ask for an account, connect with a MUD client to iweb.localecho.net,
port 4201 and ask for "Jarin".
[Digital Ocean][2] | VPS | $5/month | You can get a $50 credit if you use the referral link
https://m.do.co/c/8f64fec2670c - if you do, once you've had it long enough to have paid $25 we will
get that as a referral bonus to help Evennia development.
[Amazon Web services][3] | Cloud | ~$5/month / on-demand | Free Tier first 12 months. Regions
available around the globe.
[Amazon Lightsail][9] | Cloud | $5/month | Free first month. AWS's new "fixed cost" offering.
[Genesis MUD hosting][4] | Shell account | $8/month | Dedicated MUD host with very limited memory
offerings. As for 2017, runs a 13 years old Python version (2.4) so you'd need to either convince
them to update or compile yourself. Note that Evennia needs *at least* the "Deluxe" package (50MB
RAM) and probably *a lot* higher for a production game. This host is *not* recommended for Evennia.
[Host1Plus][5] | VPS & Cloud | $4/month | $4-$8/month depending on length of sign-up period.
[Scaleway][6] | Cloud | &euro;3/month / on-demand | EU based (Paris, Amsterdam). Smallest option
provides 2GB RAM.
[Prgmr][10] | VPS | $5/month | 1 month free with a year prepay. You likely want some experience with
servers with this option as they don't have a lot of support.
[Linode][11] | Cloud | $5/month / on-demand | Multiple regions. Smallest option provides 1GB RAM
*Please help us expand this list.*
[1]: http:silvren.com
[2]: https://www.digitalocean.com/pricing
[3]: https://aws.amazon.com/pricing/
[4]: http://www.genesismuds.com/
[5]: https://www.host1plus.com/
[6]: https://www.scaleway.com/
[7]: https://lowendbox.com/
[8]: https://www.lowendtalk.com
[9]: https://amazonlightsail.com
[10]: https://prgmr.com/
[11]: https://www.linode.com/
## Cloud9
If you are interested in running Evennia in the online dev environment [Cloud9](https://c9.io/), you
can spin it up through their normal online setup using the Evennia Linux install instructions. The
one extra thing you will have to do is update `mygame/server/conf/settings.py` and add
`WEBSERVER_PORTS = [(8080, 4001)]`. This will then let you access the web server and do everything
else as normal.
Note that, as of December 2017, Cloud9 was re-released by Amazon as a service within their AWS cloud
service offering. New customers entitled to the 1 year AWS "free tier" may find it provides
sufficient resources to operate a Cloud9 development environment without charge.
https://aws.amazon.com/cloud9/

47
docs/source/Setup/RSS.md Normal file
View file

@ -0,0 +1,47 @@
# RSS
[RSS](http://en.wikipedia.org/wiki/RSS) is a format for easily tracking updates on websites. The
principle is simple - whenever a site is updated, a small text file is updated. An RSS reader can
then regularly go online, check this file for updates and let the user know what's new.
Evennia allows for connecting any number of RSS feeds to any number of in-game channels. Updates to
the feed will be conveniently echoed to the channel. There are many potential uses for this: For
example the MUD might use a separate website to host its forums. Through RSS, the players can then
be notified when new posts are made. Another example is to let everyone know you updated your dev
blog. Admins might also want to track the latest Evennia updates through our own RSS feed
[here](http://code.google.com/feeds/p/evennia/updates/basic).
## Configuring RSS
To use RSS, you first need to install the [feedparser](http://code.google.com/p/feedparser/) python
module.
pip install feedparser
Next you activate RSS support in your config file by settting `RSS_ENABLED=True`.
Start/reload Evennia as a privileged user. You should now have a new command available, `@rss2chan`:
@rss2chan <evennia_channel> = <rss_url>
### Setting up RSS, step by step
You can connect RSS to any Evennia channel, but for testing, let's set up a new channel "rss".
@ccreate rss = RSS feeds are echoed to this channel!
Let's connect Evennia's code-update feed to this channel. The RSS url for evennia updates is
`https://github.com/evennia/evennia/commits/master.atom`, so let's add that:
@rss2chan rss = https://github.com/evennia/evennia/commits/master.atom
That's it, really. New Evennia updates will now show up as a one-line title and link in the channel.
Give the `@rss2chan` command on its own to show all connections. To remove a feed from a channel,
you specify the connection again (use the command to see it in the list) but add the `/delete`
switch:
@rss2chan/delete rss = https://github.com/evennia/evennia/commits/master.atom
You can connect any number of RSS feeds to a channel this way. You could also connect them to the
same channels as [IRC](IRC) to have the feed echo to external chat channels as well.

289
docs/source/Setup/Running-Evennia-in-Docker.md Normal file
View file

@ -0,0 +1,289 @@
# Running Evennia in Docker
Evennia has an [official docker image](https://hub.docker.com/r/evennia/evennia/) which makes
running an Evennia-based game in a Docker container easy.
## Install Evennia through docker
First, install the `docker` program so you can run the Evennia container. You can get it freely from
[docker.com](https://www.docker.com/). Linux users can likely also get it through their normal
package manager.
To fetch the latest evennia docker image, run:
docker pull evennia/evennia
This is a good command to know, it is also how you update to the latest version when we make updates
in the future. This tracks the `master` branch of Evennia.
> Note: If you want to experiment with the (unstable) `develop` branch, use `docker pull
evennia/evennia:develop`.
Next `cd` to a place where your game dir is, or where you want to create it. Then run:
docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game --user
$UID:$GID evennia/evennia
Having run this (see next section for a description of what's what), you will be at a prompt inside
the docker container:
```bash
evennia|docker /usr/src/game $
```
This is a normal shell prompt. We are in the `/usr/src/game` location inside the docker container.
If you had anything in the folder you started from, you should see it here (with `ls`) since we
mounted the current directory to `usr/src/game` (with `-v` above). You have the `evennia` command
available and can now proceed to create a new game as per the [Getting Started](Getting-Started)
instructions (you can skip the virtualenv and install 'globally' in the container though).
You can run Evennia from inside this container if you want to, it's like you are root in a little
isolated Linux environment. To exit the container and all processes in there, press `Ctrl-D`. If you
created a new game folder, you will find that it has appeared on-disk.
> The game folder or any new files that you created from inside the container will appear as owned
by `root`. If you want to edit the files outside of the container you should change the ownership.
On Linux/Mac you do this with `sudo chown myname:myname -R mygame`, where you replace `myname` with
your username and `mygame` with whatever your game folder is named.
### Description of the `docker run` command
```bash
docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game --user
$UID:$GID evennia/evennia
```
This is what it does:
- `docker run ... evennia/evennia` tells us that we want to run a new container based on the
`evennia/evennia` docker image. Everything in between are options for this. The `evennia/evennia` is
the name of our [official docker image on the dockerhub
repository](https://hub.docker.com/r/evennia/evennia/). If you didn't do `docker pull
evennia/evennia` first, the image will be downloaded when running this, otherwise your already
downloaded version will be used. It contains everything needed to run Evennia.
- `-it` has to do with creating an interactive session inside the container we start.
- `--rm` will make sure to delete the container when it shuts down. This is nice to keep things tidy
on your drive.
- `-p 4000:4000 -p 4001:4001 -p 4002:4002` means that we *map* ports `4000`, `4001` and `4002` from
inside the docker container to same-numbered ports on our host machine. These are ports for telnet,
webserver and websockets. This is what allows your Evennia server to be accessed from outside the
container (such as by your MUD client)!
- `-v $PWD:/usr/src/game` mounts the current directory (*outside* the container) to the path
`/usr/src/game` *inside* the container. This means that when you edit that path in the container you
will actually be modifying the "real" place on your hard drive. If you didn't do this, any changes
would only exist inside the container and be gone if we create a new one. Note that in linux a
shortcut for the current directory is `$PWD`. If you don't have this for your OS, you can replace it
with the full path to the current on-disk directory (like `C:/Development/evennia/game` or wherever
you want your evennia files to appear).
- `--user $UID:$GID` ensures the container's modifications to `$PWD` are done with you user and
group IDs instead of root's IDs (root is the user running evennia inside the container). This avoids
having stale `.pid` files in your filesystem between container reboots which you have to force
delete with `sudo rm server/*.pid` before each boot.
## Running your game as a docker image
If you run the `docker` command given in the previous section from your game dir you can then
easily start Evennia and have a running server without any further fuss.
But apart from ease of install, the primary benefit to running an Evennia-based game in a container
is to simplify its deployment into a public production environment. Most cloud-based hosting
providers these days support the ability to run container-based applications. This makes deploying
or updating your game as simple as building a new container image locally, pushing it to your Docker
Hub account, and then pulling from Docker Hub into your AWS/Azure/other docker-enabled hosting
account. The container eliminates the need to install Python, set up a virtualenv, or run pip to
install dependencies.
### Start Evennia and run through docker
For remote or automated deployment you may want to start Evennia immediately as soon as the docker
container comes up. If you already have a game folder with a database set up you can also start the
docker container and pass commands directly to it. The command you pass will be the main process to
run in the container. From your game dir, run for example this command:
docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game
evennia/evennia evennia start -l
This will start Evennia as the foreground process, echoing the log to the terminal. Closing the
terminal will kill the server. Note that you *must* use a foreground command like `evennia start -l`
or `evennia ipstart` to start the server - otherwise the foreground process will finish immediately
and the container go down.
### Create your own game image
These steps assume that you have created or otherwise obtained a game directory already. First, `cd`
to your game dir and create a new empty text file named `Dockerfile`. Save the following two lines
into it:
```
FROM evennia/evennia:latest
ENTRYPOINT evennia start -l
```
These are instructions for building a new docker image. This one is based on the official
`evennia/evennia` image, but also makes sure to start evennia when it runs (so we don't need to
enter it and run commands).
To build the image:
```bash
docker build -t mydhaccount/mygame .
```
(don't forget the period at the end, it will use the `Dockerfile` from the current location). Here
`mydhaccount` is the name of your `dockerhub` account. If you don't have a dockerhub account you can
build the image locally only (name the container whatever you like in that case, like just
`mygame`).
Docker images are stored centrally on your computer. You can see which ones you have available
locally with `docker images`. Once built, you have a couple of options to run your game.
### Run container from your game image for development
To run the container based on your game image locally for development, mount the local game
directory as before:
```
docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 -v $PWD:/usr/src/game --user $UID:$GID
mydhaccount/mygame
```
Evennia will start and you'll get output in the terminal, perfect for development. You should be
able to connect to the game with your clients normally.
### Deploy game image for production
Each time you rebuild the docker image as per the above instructions, the latest copy of your game
directory is actually copied inside the image (at `/usr/src/game/`). If you don't mount your on-disk
folder there, the internal one will be used. So for deploying evennia on a server, omit the `-v`
option and just give the following command:
```
docker run -it --rm -d -p 4000:4000 -p 4001:4001 -p 4002:4002 --user $UID:$GID mydhaccount/mygame
```
Your game will be downloaded from your docker-hub account and a new container will be built using
the image and started on the server! If your server environment forces you to use different ports,
you can just map the normal ports differently in the command above.
Above we added the `-d` option, which starts the container in *daemon* mode - you won't see any
return in the console. You can see it running with `docker ps`:
```bash
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED ...
f6d4ca9b2b22 mygame "/bin/sh -c 'evenn..." About a minute ago ...
```
Note the container ID, this is how you manage the container as it runs.
```
docker logs f6d4ca9b2b22
```
Looks at the STDOUT output of the container (i.e. the normal server log)
```
docker logs -f f6d4ca9b2b22
```
Tail the log (so it updates to your screen 'live').
```
docker pause f6d4ca9b2b22
```
Suspend the state of the container.
```
docker unpause f6d4ca9b2b22
```
Un-suspend it again after a pause. It will pick up exactly where it were.
```
docker stop f6d4ca9b2b22
```
Stop the container. To get it up again you need to use `docker run`, specifying ports etc. A new
container will get a new container id to reference.
## How it Works
The `evennia/evennia` docker image holds the evennia library and all of its dependencies. It also
has an `ONBUILD` directive which is triggered during builds of images derived from it. This
`ONBUILD` directive handles setting up a volume and copying your game directory code into the proper
location within the container.
In most cases, the Dockerfile for an Evennia-based game will only need the `FROM
evennia/evennia:latest` directive, and optionally a `MAINTAINER` directive if you plan to publish
your image on Docker Hub and would like to provide contact info.
For more information on Dockerfile directives, see the [Dockerfile
Reference](https://docs.docker.com/engine/reference/builder/).
For more information on volumes and Docker containers, see the Docker site's [Manage data in
containers](https://docs.docker.com/engine/tutorials/dockervolumes/) page.
### What if I Don't Want "LATEST"?
A new `evennia/evennia` image is built automatically whenever there is a new commit to the `master`
branch of Evennia. It is possible to create your own custom evennia base docker image based on any
arbitrary commit.
1. Use git tools to checkout the commit that you want to base your image upon. (In the example
below, we're checking out commit a8oc3d5b.)
```
git checkout -b my-stable-branch a8oc3d5b
```
2. Change your working directory to the `evennia` directory containing `Dockerfile`. Note that
`Dockerfile` has changed over time, so if you are going far back in the commit history you might
want to bring a copy of the latest `Dockerfile` with you and use that instead of whatever version
was used at the time.
3. Use the `docker build` command to build the image based off of the currently checked out commit.
The example below assumes your docker account is **mydhaccount**.
```
docker build -t mydhaccount/evennia .
```
4. Now you have a base evennia docker image built off of a specific commit. To use this image to
build your game, you would modify **FROM** directive in the **Dockerfile** for your game directory
to be:
```
FROM mydhacct/evennia:latest
```
Note: From this point, you can also use the `docker tag` command to set a specific tag on your image
and/or upload it into Docker Hub under your account.
5. At this point, build your game using the same `docker build` command as usual. Change your
working directory to be your game directory and run
```
docker build -t mydhaccountt/mygame .
```
## Additional Creature Comforts
The Docker ecosystem includes a tool called `docker-compose`, which can orchestrate complex multi-
container applications, or in our case, store the default port and terminal parameters that we want
specified every time we run our container. A sample `docker-compose.yml` file to run a containerized
Evennia game in development might look like this:
```
version: '2'
services:
evennia:
image: mydhacct/mygame
stdin_open: true
tty: true
ports:
- "4001-4002:4001-4002"
- "4000:4000"
volumes:
- .:/usr/src/game
```
With this file in the game directory next to the `Dockerfile`, starting the container is as simple
as
```
docker-compose up
```
For more information about `docker-compose`, see [Getting Started with docker-
compose](https://docs.docker.com/compose/gettingstarted/).
> Note that with this setup you lose the `--user $UID` option. The problem is that the variable
`UID` is not available inside the configuration file `docker-compose.yml`. A workaround is to
hardcode your user and group id. In a terminal run `echo $UID:$GID` and if for example you get
`1000:1000` you can add to `docker-compose.yml` a line `user: 1000:1000` just below the `image: ...`
line.

152
docs/source/Setup/Security.md Normal file
View file

@ -0,0 +1,152 @@
# Security
Hackers these days aren't discriminating, and their backgrounds range from bored teenagers to
international intelligence agencies. Their scripts and bots endlessly crawl the web, looking for
vulnerable systems they can break into. Who owns the system is irrelevant-- it doesn't matter if it
belongs to you or the Pentagon, the goal is to take advantage of poorly-secured systems and see what
resources can be controlled or stolen from them.
If you're considering deploying to a cloud-based host, you have a vested interest in securing your
applications-- you likely have a credit card on file that your host can freely bill. Hackers pegging
your CPU to mine cryptocurrency or saturating your network connection to participate in a botnet or
send spam can run up your hosting bill, get your service suspended or get your address/site
blacklisted by ISPs. It can be a difficult legal or political battle to undo this damage after the
fact.
As a developer about to expose a web application to the threat landscape of the modern internet,
here are a few tips to consider to increase the security of your Evennia install.
### Know your logs
In case of emergency, check your logs! By default they are located in the `server/logs/` folder.
Here are some of the more important ones and why you should care:
* `http_requests.log` will show you what HTTP requests have been made against Evennia's built-in
webserver (TwistedWeb). This is a good way to see if people are innocuously browsing your site or
trying to break it through code injection.
* `portal.log` will show you various networking-related information. This is a good place to check
for odd or unusual types or amounts of connections to your game, or other networking-related
issues-- like when users are reporting an inability to connect.
* `server.log` is the MUX administrator's best friend. Here is where you'll find information
pertaining to who's trying to break into your system by guessing at passwords, who created what
objects, and more. If your game fails to start or crashes and you can't tell why, this is the first
place you should look for answers. Security-related events are prefixed with an `[SS]` so when
there's a problem you might want to pay special attention to those.
### Disable development/debugging options
There are a few Evennia/Django options that are set when you first create your game to make it more
obvious to you where problems arise. These options should be disabled before you push your game into
production-- leaving them on can expose variables or code someone with malicious intent can easily
abuse to compromise your environment.
In `server/conf/settings.py`:
# Disable Django's debug mode
DEBUG = False
# Disable the in-game equivalent
IN_GAME_ERRORS = False
# If you've registered a domain name, force Django to check host headers. Otherwise leave this
as-is.
# Note the leading period-- it is not a typo!
ALLOWED_HOSTS = ['.example.com']
### Handle user-uploaded images with care
If you decide to allow users to upload their own images to be served from your site, special care
must be taken. Django will read the file headers to confirm it's an image (as opposed to a document
or zip archive), but [code can be injected into an image
file](https://insinuator.net/2014/05/django-image-validation-vulnerability/) *after* the headers
that can be interpreted as HTML and/or give an attacker a web shell through which they can access
other filesystem resources.
[Django has a more comprehensive overview of how to handle user-uploaded
files](https://docs.djangoproject.com/en/dev/topics/security/#user-uploaded-content-security), but
in short you should take care to do one of two things--
* Serve all user-uploaded assets from a *separate* domain or CDN (*not* a subdomain of the one you
already have!). For example, you may be browsing `reddit.com` but note that all the user-submitted
images are being served from the `redd.it` domain. There are both security and performance benefits
to this (webservers tend to load local resources one-by-one, whereas they will request external
resources in bulk).
* If you don't want to pay for a second domain, don't understand what any of this means or can't be
bothered with additional infrastructure, then simply reprocess user images upon receipt using an
image library. Convert them to a different format, for example. *Destroy the originals!*
### Disable the web interface
The web interface allows visitors to see an informational page as well as log into a browser-based
telnet client with which to access Evennia. It also provides authentication endpoints against which
an attacker can attempt to validate stolen lists of credentials to see which ones might be shared by
your users. Django's security is robust, but if you don't want/need these features and fully intend
to force your users to use traditional clients to access your game, you might consider disabling
either/both to minimize your attack surface.
In `server/conf/settings.py`:
# Disable the Javascript webclient
WEBCLIENT_ENABLED = False
# Disable the website altogether
WEBSERVER_ENABLED = False
### Change your ssh port
Automated attacks will often target port 22 seeing as how it's the standard port for SSH traffic.
Also,
many public wifi hotspots block ssh traffic over port 22 so you might not be able to access your
server from these locations if you like to work remotely or don't have a home internet connection.
If you don't intend on running a website or securing it with TLS, you can mitigate both problems by
changing the port used for ssh to 443, which most/all hotspot providers assume is HTTPS traffic and
allows through.
(Ubuntu) In /etc/ssh/sshd_config, change the following variable:
# What ports, IPs and protocols we listen for
Port 443
Save, close, then run the following command:
sudo service ssh restart
### Set up a firewall
Ubuntu users can make use of the simple ufw utility. Anybody else can use iptables.
# Install ufw (if not already)
sudo apt-get install ufw
UFW's default policy is to deny everything. We must specify what we want to allow through our
firewall.
# Allow terminal connections to your game
sudo ufw allow 4000/tcp
# Allow browser connections to your website
sudo ufw allow 4001/tcp
Use ONE of the next two commands depending on which port your ssh daemon is listening on:
sudo ufw allow 22/tcp
sudo ufw allow 443/tcp
Finally:
sudo ufw enable
Now the only ports open will be your administrative ssh port (whichever you chose), and Evennia on
4000-4001.
### Use an external webserver
Though not officially supported, there are some benefits to [deploying a webserver](Apache-Config)
to handle/proxy traffic to your Evennia instance.
For example, Evennia's game engine and webservice are tightly integrated. If you bring your game
down for maintenance (or if it simply crashes) your website will go down with it. In these cases a
standalone webserver can still be used to display a maintenance page or otherwise communicate to
your users the reason for the downtime, instead of disappearing off the face of the earth and
returning opaque `SERVER NOT FOUND` error messages.
Proper webservers are also written in more efficient programming languages than Python, and while
Twisted can handle its own, putting a webserver in front of it is like hiring a bouncer to deal with
nuisances and crowds before they even get in the door.
Many of the popular webservers also let you plug in additional modules (like
[mod_security](https://en.wikipedia.org/wiki/ModSecurity) for Apache) that can be used to detect
(and block!) malicious users or requests before they even touch your game or site. There are also
automated solutions for installing and configuring TLS (via [Certbot/Let's
Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt)) to secure your website against hotspot and
ISP snooping.

196
docs/source/Setup/Start-Stop-Reload.md Normal file
View file

@ -0,0 +1,196 @@
# Start Stop Reload
You control Evennia from your game folder (we refer to it as `mygame/` here), using the `evennia`
program. If the `evennia` program is not available on the command line you must first install
Evennia as described in the [Getting Started](Getting-Started) page.
> Hint: If you ever try the `evennia` command and get an error complaining that the command is not
available, make sure your [virtualenv](Glossary#virtualenv) is active.
Below are described the various management options. Run
evennia -h
to give you a brief help and
evennia menu
to give you a menu with options.
## Starting Evennia
Evennia consists of two components, the Evennia [Server and Portal](Portal-And-Server). Briefly,
the *Server* is what is running the mud. It handles all game-specific things but doesn't care
exactly how players connect, only that they have. The *Portal* is a gateway to which players
connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the
game. Both are required for a functioning mud.
evennia start
The above command will start the Portal, which in turn will boot up the Server. The command will
print a summary of the process and unless there is an error you will see no further output. Both
components will instead log to log files in `mygame/server/logs/`. For convenience you can follow
those logs directly in your terminal by attaching `-l` to commands:
evennia -l
Will start following the logs of an already running server. When starting Evennia you can also do
evennia start -l
> To stop viewing the log files, press `Ctrl-C`.
## Foreground mode
Normally, Evennia runs as a 'daemon', in the background. If you want you can start either of the
processes (but not both) as foreground processes in *interactive* mode. This means they will log
directly to the terminal (rather than to log files that we then echo to the terminal) and you can
kill the process (not just the log-file view) with `Ctrl-C`.
evennia istart
will start/restart the *Server* in interactive mode. This is required if you want to run a
*debugger*. Next time you reload the server, it will return to normal mode.
evennia ipstart
will start the *Portal* in interactive mode. This is usually only necessary if you want to run
Evennia under the control of some other type of process.
## Reloading
The act of *reloading* means the Portal will tell the Server to shut down and then boot it back up
again. Everyone will get a message and the game will be briefly paused for all accounts as the
server
reboots. Since they are connected to the *Portal*, their connections are not lost.
Reloading is as close to a "warm reboot" you can get. It reinitializes all code of Evennia, but
doesn't kill "persistent" [Scripts](Scripts). It also calls `at_server_reload()` hooks on all
objects so you
can save eventual temporary properties you want.
From in-game the `@reload` command is used. You can also reload the server from outside the game:
evennia reload
Sometimes reloading from "the outside" is necessary in case you have added some sort of bug that
blocks in-game input.
## Resetting
*Resetting* is the equivalent of a "cold reboot" - the Server will shut down and then restarted
again, but will behave as if it was fully shut down. As opposed to a "real" shutdown, no accounts
will be disconnected during a
reset. A reset will however purge all non-persistent scripts and will call `at_server_shutdown()`
hooks. It can be a good way to clean unsafe scripts during development, for example.
From in-game the `@reset` command is used. From the terminal:
evennia reset
## Rebooting
This will shut down *both* Server and Portal, which means all connected players will lose their
connection. It can only be initiated from the terminal:
evennia reboot
This is identical to doing these two commands:
evennia stop
evennia start
## Shutting down
A full shutdown closes Evennia completely, both Server and Portal. All accounts will be booted and
systems saved and turned off cleanly.
From inside the game you initiate a shutdown with the `@shutdown` command. From command line you do
evennia stop
You will see messages of both Server and Portal closing down. All accounts will see the shutdown
message and then be disconnected. The same effect happens if you press `Ctrl+C` while the server
runs in interactive mode.
## Status and info
To check basic Evennia settings, such as which ports and services are active, this will repeat the
initial return given when starting the server:
evennia info
You can also get a briefer run-status from both components with this command
evennia status
This can be useful for automating checks to make sure the game is running and is responding.
## Killing (Linux/Mac only)
In the extreme case that neither of the server processes locks up and does not respond to commands,
you can send them kill-signals to force them to shut down. To kill only the Server:
evennia skill
To kill both Server and Portal:
evennia kill
Note that this functionality is not supported on Windows.
## Django options
The `evennia` program will also pass-through options used by the `django-admin`. These operate on
the database in various ways.
```bash
evennia migrate # migrate the database
evennia shell # launch an interactive, django-aware python shell
evennia dbshell # launch database shell
```
For (many) more options, see [the django-admin
docs](https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage).
## Advanced handling of Evennia processes
If you should need to manually manage Evennia's processors (or view them in a task manager program
such as Linux' `top` or the more advanced `htop`), you will find the following processes to be
related to Evennia:
* 1 x `twistd ... evennia/server/portal/portal.py` - this is the Portal process.
* 3 x `twistd ... server.py` - One of these processes manages Evennia's Server component, the main
game. The other processes (with the same name but different process id) handle's Evennia's
internal web server threads. You can look at `mygame/server/server.pid` to determine which is the
main process.
### Syntax errors during live development
During development, you will usually modify code and then reload the server to see your changes.
This is done by Evennia re-importing your custom modules from disk. Usually bugs in a module will
just have you see a traceback in the game, in the log or on the command line. For some really
serious syntax errors though, your module might not even be recognized as valid Python. Evennia may
then fail to restart correctly.
From inside the game you see a text about the Server restarting followed by an ever growing list of
"...". Usually this only lasts a very short time (up to a few seconds). If it seems to go on, it
means the Portal is still running (you are still connected to the game) but the Server-component of
Evennia failed to restart (that is, it remains in a shut-down state). Look at your log files or
terminal to see what the problem is - you will usually see a clear traceback showing what went
wrong.
Fix your bug then run
evennia start
Assuming the bug was fixed, this will start the Server manually (while not restarting the Portal).
In-game you should now get the message that the Server has successfully restarted.