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

Revert "Updated HTML docs."

Browse source 
This reverts commit 06bc3c8bcd.
This commit is contained in:
Griatch 2022-11-15 20:46:50 +01:00
parent 06bc3c8bcd
commit a452434ba8
663 changed files with 61705 additions and 2 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](https://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).

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

@ -0,0 +1,342 @@
# 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](https://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](https://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}
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.
### Advanced Postgresql Usage (Remote Server)
```{warning}
The example below is for a server within a private network that is not open to
the Internet. Be sure to understand the details before making any changes to
an Internet-accessible server.
```
The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.
Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.
First, determine which cluster is running your database. Use `pg_lscluster`:
```bash
$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
12 main 5432 online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
```
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems
in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are
what are reported in the `pg_lscluster` output. So, for the above example,
the file is `/etc/postgresql/12/main/postgresql.conf`.
In this file, look for the line with `listen_addresses`. For example:
```
listen_address = 'localhost' # What IP address(es) to listen on;
# comma-separated list of addresses;
# defaults to 'localhost'; use '*' for all
```
```{warning}
Misconfiguring the wrong cluster may cause problems
with existing clusters.
```
Also, note the line with `port =` and keep the port number in mind.
Set `listen_addresses` to `'*'`. This permits postgresql to accept connections
on any interface.
```{warning}
Setting `listen_addresses` to `'*'` opens a port on all interfaces. If your
server has access to the Internet, ensure your firewall is configured
appropriately to limit access to this port as necessary. (You may also list
explicit addresses and subnets to listen. See the postgresql documentation
for more details.)
```
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`).
Look for a line with:
```
# IPv4 local connections:
host all all 127.0.0.1/32 md5
```
Add a line with:
```
host all all 0.0.0.0/0 md5
```
```{warning}
This permits incoming connections from *all* IPs. See
the PosgreSQL documentation on how to limit this.
```
Now, restart your cluster:
```bash
$ pg_ctlcluster 12 main restart
```
Finally, update the database settings in your Evennia secret_settings.py (as
described [above](#evennia-postgresql-configuration) modifying `SERVER` and
`PORT` to match your server.
Now your Evennia installation should be able to connect and talk with a remote
server.
## 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](https://code.google.com/p/django-mssql/) and possibly a few
others. If you try other databases out, consider expanding this page with instructions.

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

@ -0,0 +1,84 @@
# Client Support Grid
This grid tries to gather info about different MU clients when used with Evennia.
If you want to report a problem, update an entry or add a client, make a
new [documentation issue](github:issue) for it. Everyone's encouraged to report their findings.
## Client Grid
Legend:
- **Name**: The name of the client. Also note if it's OS-specific.
- **Version**: Which version or range of client versions were tested.
- **Comments**: Any quirks on using this client with Evennia should be added here.
| Name | Version tested | Comments |
| --- | --- | --- |
| [Evennia Webclient][1] | 1.0+ | Evennia-specific |
| [tintin++][2] | 2.0+ | No MXP support |
| [tinyfugue][3] | 5.0+ | No UTF-8 support |
| [MUSHclient][4] (Win) | 4.94 | NAWS reports full text area |
| [Zmud][5] (Win) | 7.21 | *UNTESTED* |
| [Cmud][6] (Win) | v3 | *UNTESTED* |
| [Potato][7]_ | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand |
| | | "localhost", must use `127.0.0.1`. |
| [Mudlet][8] | 3.4+ | No known issues. Some older versions showed <> as html |
| | | under MXP. |
| [SimpleMU][9] (Win) | full | Discontinued. NAWS reports pixel size. |
| [Atlantis][10] (Mac) | 0.9.9.4 | No known issues. |
| [GMUD][11] | 0.0.1 | Can't handle any telnet handshakes. Not recommended. |
| [BeipMU][12] (Win) | 3.0.255 | No MXP support. Best to enable "MUD prompt handling", disable |
| | | "Handle HTML tags". |
| [MudRammer][13] (IOS) | 1.8.7 | Bad Telnet Protocol compliance: displays spurious characters. |
| [MUDMaster][14] | 1.3.1 | *UNTESTED* |
| [BlowTorch][15] (Andr) | 1.1.3 | Telnet NOP displays as spurious character. |
| [Mukluk][16] (Andr) | 2015.11.20| Telnet NOP displays as spurious character. Has UTF-8/Emoji |
| | | support. |
| [Gnome-MUD][17] (Unix) | 0.11.2 | Telnet handshake errors. First (only) attempt at logging in |
| | | fails. |
| [Spyrit][18] | 0.4 | No MXP, OOB support. |
| [JamochaMUD][19] | 5.2 | Does not support ANSI within MXP text. |
| [DuckClient][20] (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][21] | 2.11.1 | No known issues. |
[1]: ../Components/Webclient
[2]: http://tintin.sourceforge.net/
[3]: http://tinyfugue.sourceforge.net/
[4]: https://mushclient.com/
[5]: http://forums.zuggsoft.com/index.php?page=4&action=file&file_id=65
[6]: http://forums.zuggsoft.com/index.php?page=4&action=category&cat_id=11
[7]: https://www.potatomushclient.com/
[8]: https://www.mudlet.org/
[9]: https://archive.org/details/tucows_196173_SimpleMU_MU_Client
[10]: https://www.riverdark.net/atlantis/
[11]: https://sourceforge.net/projects/g-mud/
[12]: http://www.beipmu.com/
[13]: https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072
[14]: https://itunes.apple.com/us/app/mudmaster/id341160033
[15]: https://bt.happygoatstudios.com/
[16]: https://play.google.com/store/apps/details?id=com.crap.mukluk
[17]: https://github.com/GNOME/gnome-mud
[18]: https://spyrit.ierne.eu.org/
[19]: https://jamochamud.org/
[20]: http://duckclient.com/
[21]: https://www.kildclient.org/
## Workarounds for client issues:
### Issue: Telnet NOP displays as spurious character.
Known clients:
* BlowTorch (Andr)
* Mukluk (Andr)
Workaround:
* In-game: Use `@option NOPKEEPALIVE=off` for the session, or use the `/save`
parameter to disable it for that Evennia account permanently.
* Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client.

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](https://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.

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

@ -0,0 +1,71 @@
# Grapevine
[Grapevine](https://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!

243
docs/source/Setup/HAProxy-Config.md Normal file
View file

@ -0,0 +1,243 @@
# Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together
A modern public-facing website should these days be served via encrypted
connections. So `https:` rather than `http:` for the website and
`wss:` rather than vs `ws:` for websocket connections used by webclient.
The reason is security - not only does it make sure a user ends up at the right
site (rather than a spoof that hijacked the original's address), it stops an
evil middleman from snooping on data (like passwords) being sent across the
wire.
Evennia itself does not implement https/wss connections. This is something best
handled by dedicated tools able to keep up-to-date with the latest security
practices.
So what we'll do is install _proxy_ between Evennia and the outgoing ports of
your server. Essentially, Evennia will think it's only running locally (on
localhost, IP 127.0.0.1) while the proxy will transparently map that to the
"real" outgoing ports and handle HTTPS/WSS for us.
Evennia
|
(inside-only local IP/ports serving HTTP/WS)
|
Proxy
|
(outside-visible public IP/ports serving HTTPS/WSS)
|
Firewall
|
Internet
These instructions assume you run a server with Unix/Linux (very common if you
use remote hosting) and that you have root access to that server.
The pieces we'll need:
- [HAProxy](https://www.haproxy.org/) - an open-source proxy program that is
easy to set up and use.
- [LetsEncrypt](https://letsencrypt.org/getting-started/) for providing the User
Certificate needed to establish an encrypted connection. In particular we'll
use the excellent [Certbot](https://certbot.eff.org/instructions) program,
which automates the whole certificate setup process with LetsEncrypt.
- `cron` - this comes with all Linux/Unix systems and allows to automate tasks
in the OS.
Before starting you also need the following information and setup:
- (optional) The host name of your game. This is
something you must previously have purchased from a _domain registrar_ and set
up with DNS to point to the IP of your server. For the benefit of this
manual, we'll assume your host name is `my.awesomegame.com`.
- If you don't have a domain name or haven't set it up yet, you must at least
know the IP address of your server. Find this with `ifconfig` or similar from
inside the server. If you use a hosting service like DigitalOcean you can also
find the droplet's IP address in the control panel. Use this as the host name
everywhere.
- You must open port 80 in your firewall. This is used by Certbot below to
auto-renew certificates. So you can't really run another webserver alongside
this setup without tweaking.
- You must open port 443 (HTTPS) in your firewall. This will be the external
webserver port.
- Make sure port 4001 (internal webserver port) is _not_ open in your firewall
(it usually will be closed by default unless you explicitly opened it
previously).
- Open port 4002 in firewall (we'll use the same number for both internal-
and external ports, the proxy will only show the safe one serving wss).
## Getting certificates
Certificates guarantee that you are you. Easiest is to get this with
[Letsencrypt](https://letsencrypt.org/getting-started/) and the
[Certbot](https://certbot.eff.org/instructions) program. Certbot has a lot of
install instructions for various operating systems. Here's for Debian/Ubuntu:
sudo apt install certbot
Make sure to stop Evennia and that no port-80 using service is running, then
sudo certbot certonly --standalone
You will get some questions you need to answer, such as an email to send
certificate errors to and the host name (or IP, supposedly) to use with this
certificate. After this, the certificates will end up in
`/etc/letsencrypt/live/<yourhostname>/*pem` (example from Ubuntu). The
critical files for our purposes are `fullchain.pem` and `privkey.pem`.
Certbot sets up a cron-job/systemd job to regularly renew the certificate. To
check this works, try
```
sudo certbot renew --dry-run
```
The certificate is only valid for 3 months at a time, so make sure this test
works (it requires port 80 to be open). Look up Certbot's page for more help.
We are not quite done. HAProxy expects these two files to be _one_ file. More
specifically we are going to
1. copy `privkey.pem` and copy it to a new file named `<yourhostname>.pem` (like
`my.awesomegame.com.pem`)
2. Append the contents of `fullchain.pem` to the end of this new file. No empty
lines are needed.
We could do this by copy&pasting in a text editor, but here's how to do it with
shell commands (replace the example paths with your own):
cd /etc/letsencrypt/live/my.awesomegame.com/
sudo cp privkey.pem my.awesomegame.com.pem
sudo cat fullchain.pem >> my.awesomegame.com.pem
The new `my.awesomegame.com.pem` file (or whatever you named it) is what we will
point to in the HAProxy config below.
There is a problem here though - Certbot will (re)generate `fullchain.pem` for
us automatically a few days before before the 3-month certificate runs out.
But HAProxy will not see this because it is looking at the combined file that
will still have the old `fullchain.pem` appended to it.
We'll set up an automated task to rebuild the `.pem` file regularly by
using the `cron` program of Unix/Linux.
crontab -e
An editor will open to the crontab file. Add the following at the bottom (all
on one line, and change the paths to your own!):
0 5 * * * cd /etc/letsencrypt/live/my.awesomegame.com/ &&
cp privkey.pem my.awesomegame.com.pem &&
cat fullchain.pem >> my.awesomegame.com.pem
Save and close the editor. Every night at 05:00 (5 AM), the
`my.awesomegame.com.pem` will now be rebuilt for you. Since Certbot updates
the `fullchain.pem` file a few days before the certificate runs out, this should
be enough time to make sure HaProxy never sees an outdated certificate.
## Installing and configuring HAProxy
Installing HaProxy is usually as simple as:
# Debian derivatives (Ubuntu, Mint etc)
sudo apt install haproxy
# Redhat derivatives (dnf instead of yum for very recent Fedora distros)
sudo yum install haproxy
Configuration of HAProxy is done in a single file. This can be located wherever
you like, for now put in your game dir and name it `haproxy.cfg`.
Here is an example tested on Centos7 and Ubuntu. Make sure to change the file to
put in your own values.
We use the `my.awesomegame.com` example here and here are the ports
- `443` is the standard SSL port
- `4001` is the standard Evennia webserver port (firewall closed!)
- `4002` is the default Evennia websocket port (we use the same number for
the outgoing wss port, so this should be open in firewall).
```shell
# base stuff to set up haproxy
global
log /dev/log local0
chroot /var/lib/haproxy
maxconn 4000
user haproxy
tune.ssl.default-dh-param 2048
## uncomment this when everything works
# daemon
defaults
mode http
option forwardfor
# Evennia Specifics
listen evennia-https-website
bind my.awesomegame.com:443 ssl no-sslv3 no-tlsv10 crt /etc/letsencrypt/live/my.awesomegame.com>/my.awesomegame.com.pem
server localhost 127.0.0.1:4001
timeout client 10m
timeout server 10m
timeout connect 5m
listen evennia-secure-websocket
bind my.awesomegame.com:4002 ssl no-sslv3 no-tlsv10 crt /etc/letsencrypt/live/my.awesomegame.com/my.awesomegame.com.pem
server localhost 127.0.0.1:4002
timeout client 10m
timeout server 10m
timeout connect 5m
```
## Putting it all together
Get back to the Evennia game dir and edit mygame/server/conf/settings.py. Add:
WEBSERVER_INTERFACES = ['127.0.0.1']
WEBSOCKET_CLIENT_INTERFACE = '127.0.0.1'
and
WEBSOCKET_CLIENT_URL="wss://my.awesomegame.com:4002/"
Make sure to reboot (stop + start) evennia completely:
evennia reboot
Finally you start the proxy:
```
sudo haproxy -f /path/to/the/above/haproxy.cfg
```
Make sure you can connect to your game from your browser and that you end up
with an `https://` page and can use the websocket webclient.
Once everything works you may want to start the proxy automatically and in the
background. Stop the proxy with `Ctrl-C` and make sure to uncomment the line `#
daemon` in the config file.
If you have no other proxies running on your server, you can copy your
haproxy.conf file to the system-wide settings:
sudo cp /path/to/the/above/haproxy.cfg /etc/haproxy/
The proxy will now start on reload and you can control it with
sudo service haproxy start|stop|restart|status
If you don't want to copy stuff into `/etc/` you can also run the haproxy purely
out of your current location by running it with `cron` on server restart. Open
the crontab again:
sudo crontab -e
Add a new line to the end of the file:
@reboot haproxy -f /path/to/the/above/haproxy.cfg
Save the file and haproxy should start up automatically when you reboot the
server. Next just restart the proxy manually a last time - with `daemon`
uncommented in the config file, it will now start as a background process.

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](https://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](../Components/Commands.md) 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](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md)
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(f"Your tweet was {tlen} chars long (max 280).")
return
# post the tweet
TWITTER_API.PostUpdate(tweet)
caller.msg(f"You tweeted:\n{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](../Components/Locks.md) 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](../Howtos/Tutorial-Tweeting-Game-Stats.md) for
help.

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

@ -0,0 +1,85 @@
# IRC
[IRC (Internet Relay Chat)](https://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](../Components/Channels.md) 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](https://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](https://www.irchelp.org/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!

148
docs/source/Setup/Installation-Android.md Normal file
View file

@ -0,0 +1,148 @@
# 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.
```{warning}
Android installation is experimental and not tested with later versions of Android.
Report your findings.
```
## 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](./Installation-Android.md#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
[Setup Quickstart](./Installation.md) 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](./Installation-Git.md#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/

281
docs/source/Setup/Installation-Docker.md Normal file
View file

@ -0,0 +1,281 @@
# Installing with Docker
Evennia releases [docker images](https://hub.docker.com/r/evennia/evennia/) which makes
running an Evennia-based game in a Docker container easy.
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 will get the latest stable image.
docker pull evennia/evennia:develop
gets the image based off Evennia's unstable `develop` branch.
Next, `cd` to a place where your game dir is, or where you want to create it. Then run:
```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
```
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 normal [game setup](./Installation.md)
instructions (no virtualenv needed).
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.
Below is an explanation of the `docker run` command we used:
- `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.

259
docs/source/Setup/Installation-Git.md Normal file
View file

@ -0,0 +1,259 @@
# Installing with GIT
This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia itself or have an easier time exploring the code. See the basic [Installation](./Installation.md) for
a quick installation of the library. See the [troubleshooting](./Installation-Troubleshooting.md) if you run
into trouble.
```{important}
If you are converting an existing game from a previous version, [see here](./Installation-Upgrade.md).
```
## Summary
For the impatient. If you have trouble with a step, you should jump on to the
more detailed instructions for your platform.
```{warning}
Currently, these instructions will install 'latest' (stable) Evennia, which is
the 0.9.5 version. To install 1.0-dev, you need to add a step `git checkout develop` between steps
3 and 4 below.
```
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` (a new folder `evennia` is created)
4. `python3.10 -m venv evenv` (a new folder `evenv` is created)
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`).
## Linux Install
For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the requirements:
```
sudo apt-get update
sudo apt-get install python3.10 python3.10-venv python3.10-dev gcc
```
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.md#virtualenv).
```
python3.10 -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 (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
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).
## 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](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
if you are unsure how it works.
* Python should already be installed but you must make sure it's a high enough version - go for
3.10.
([This](https://docs.python-guide.org/en/latest/starting/install/osx/) discusses
how you may upgrade it).
* GIT can be obtained with
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or via MacPorts [as described
here](https://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.md#virtualenv).
```
python3.10 -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:
```
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
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).
## Windows Install
> If you are running Windows10, consider using the _Windows Subsystem for Linux_
> ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead.
> Just set up WSL with an Ubuntu image and 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](https://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. Get Python any version of Python **3.10**, 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](https://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.md#virtualenv).
```
python3.10 -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
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).

19
docs/source/Setup/Installation-Non-Interactive.md Normal file
View file

@ -0,0 +1,19 @@
# Non-interactive setup
The first time you run `evennia start` (just after having created the database), you will be asked
to interactively insert the superuser username, email and password. If you are deploying Evennia
as part of an automatic build script, you don't want to enter this information manually.
You can have the superuser be created automatically by passing environment variables to your
build script:
- `EVENNIA_SUPERUSER_USERNAME`
- `EVENNIA_SUPERUSER_PASSWORD`
- `EVENNIA_SUPERUSER_EMAIL` is optional. If not given, empty string is used.
These envvars will only be used on the _very first_ server start and then ignored. For example:
```
EVENNIA_SUPERUSER_USERNAME=myname EVENNIA_SUPERUSER_PASSWORD=mypwd evennia start
```

137
docs/source/Setup/Installation-Troubleshooting.md Normal file
View file

@ -0,0 +1,137 @@
# Installation Troubleshooting
If you have an issue not covered here, [please report it](https://github.com/evennia/evennia/issues/new/choose)
so it can be fixed or a workaround found!
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`.
## Check your Requirements
Any system that supports Python3.9+ should work. We'll describe how to install
everything in the following sections.
- Linux/Unix
- Windows (Win7, Win8, Win10, Win11)
- Mac OSX (>10.5 recommended)
- [Python](https://www.python.org) (v3.9 and 3.10 are tested)
- [virtualenv](https://pypi.python.org/pypi/virtualenv) for making isolated
Python environments. Installed with `pip install virtualenv`.
- [Twisted](https://twistedmatrix.com) (v22.0+)
- [ZopeInterface](https://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](https://www.djangoproject.com) (v4.0.1+), be warned that latest dev
version is usually untested with Evennia.
- [GIT](https://git-scm.com/) - version control software used if you want to install the sources
(but also useful to track your own code) - Mac users can use the
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or the
[MacPorts version](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
## Confusion of location (GIT installation)
It's common to be confused and install Evennia in the wrong location. After following the
[git install](./Installation-Git.md) instructions, the folder structure should look like this:
```
muddev/
evenv/
evennia/
mygame/
```
The evennia code itself is found inside `evennia/evennia/` (so two levels down). Your settings file
is `mygame/server/conf/settings.py` and the _parent_ setting file is `evennia/evennia/settings_default.py`.
## Virtualenv setup fails
When doing the `python3.10 -m venv evenv` step, some users report getting an error; something like:
Error: Command '['evenv', '-Im', 'ensurepip', '--upgrade', '--default-pip']'
returned non-zero exit status 1
You can solve this by installing the `python3.10-venv` package or equivalent for your OS. Alternatively
you can bootstrap it in this way:
python3.10 -m --without-pip evenv
This should set up the virtualenv without `pip`. Activate the new virtualenv and then install pip from within it:
python -m ensurepip --upgrade
If that fails, a worse alternative to try is
curl https://bootstrap.pypa.io/get-pip.py | python3.10 (linux/unix/WSL only)
Either way, you should now be able to continue with the installation.
## Localhost not found
If `localhost` doesn't work when trying to connect to your local game, try `127.0.0.1`, which is the same thing.
## 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.
- When doing a [git install](./Installation-Git.md), some not-updated Linux distributions may give errors
about 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
- Install Python [from the Python homepage](https://www.python.org/downloads/windows/). You will
need to be a Windows Administrator to install packages.
- When installing Python, 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.
- If you get a `command not found` when trying to run the `evennia` program after installation, try closing the
Console and starting it again (remember to re-activate the virtualenv!). Sometimes Windows is not updating
its environment properly.
- 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`.
- 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 `22.1` failed, install `22.0` manually with `pip
install twisted==22.0`. Alternatively you could check that you are using the 64-bit version of Python
and uninstall any 32bit one. If so, you must then `deactivate` the virtualenv, delete the `evenv` folder
and recreate it anew with your new Python.
- 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.
- Some users have reported issues with Windows WSL and anti-virus software during Evennia
development. Timeout errors and the inability to run `evennia connections` may be due to your anti-
virus software interfering. Try disabling or changing your anti-virus software settings.

45
docs/source/Setup/Installation-Upgrade.md Normal file
View file

@ -0,0 +1,45 @@
# Upgrading an existing installation
## Evennia v0.9.5 to 1.0
Prior to 1.0, all Evennia installs were [Git-installs](./Installation-Git.md). These instructions
assume that you have a cloned `evennia` repo and use a virtualenv (best practices).
- Make sure to stop Evennia 0.9.5 entirely with `evennia stop`.
- `deactivate` to leave your active virtualenv.
- Make a _backup_ of your entire `mygame` folder, just to be sure!
- Delete the old `evenv` folder, or rename it (in case you want to keep using 0.9.5 for a while).
- Install Python 3.10 (recommended) or 3.9. Follow the [Git-installation](./Installation-Git.md) for your OS if needed.
- If using virtualenv, make a _new_ one with `python3.10 -m venv evenv`, then activate with `source evenv/bin/activate`
(linux/mac) or `\evenv\Script\activate` (windows)
- `cd` into your `evennia/` folder (you want to see the `docs/`, `bin/` directories as well as a nested `evennia/` folder)
- **Prior to 1.0 release only** - do `git checkout develop` to switch to the develop branch. After release, this will
be found on the default master branch.
- `git pull`
- `pip install -e .`
- If you want the optional extra libs, do `pip install -r requirements_extra.txt`.
- Test that you can run the `evennia` command.
If you don't have anything you want to keep in your existing game dir, you can just start a new onew
using the normal [install instructions](./Installation.md). If you want to keep/convert your existing
game dir, continue below.
- First, make a backup of your exising game dir! If you use version control, make sure to commit your current state.
- `cd` to your existing 0.9.5-based game folder (like `mygame`.)
- If you have changed `mygame/web`, _rename_ the folder to `web_0.9.5`. If you didn't change anything (or don't have
anything you want to keep), you can _delete_ it entirely.
- Copy `evennia/evennia/game_template/web` to `mygame/` (e.g. using `cp -Rf` or a file manager). This new `web` folder
replaces the old one and has a very different structure.
- It's possible you need to replace/comment out import and calls to the deprecated
[`django.conf.urls`](https://docs.djangoproject.com/en/3.2/ref/urls/#url). The new way to call it is
[available here](https://docs.djangoproject.com/en/4.0/ref/urls/#django.urls.re_path).
- Run `evennia migrate`
- Run `evennia start`
If you made extensive work in your game dir, you may well find that you need to do some (hopefully minor)
changes to your code before it will start with Evennia 1.0. Some important points:
- The `evennia/contrib/` folder changed structure - there are now categorized sub-folders, so you have to update
your imports.
- Any `web` changes need to be moved back from your backup into the new structure of `web/` manually.
- See the [Evennia 1.0 Changelog](../Coding/Changelog.md) for all changes.

112
docs/source/Setup/Installation.md Normal file
View file

@ -0,0 +1,112 @@
# Installation
```{warning}
pip install evennia is not yet available in develop branch. Use the [git installation](./Installation-Git.md).
```
```{important}
If you are converting an existing game from a previous version, [see here](./Installation-Upgrade.md).
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.9 or 3.10.
- Using a [Python virtualenv](../Glossary.md#virtualenv) is highly recommended in order to keep your
Evennia installation independent from the system libraries.
- Don't install Evennia as
administrator or superuser.
Evennia is managed from the terminal (console/CMD on Windows). If you have a suitable Python installed, you can install with
pip install evennia
Alternatively, you can [install Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md).
Installing doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection.
Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it's active whenever you need to use the `evennia` command.
> Check out [installation troubleshooting](./Installation-Troubleshooting.md) if you run into problems. Some
users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Initialize a new game
Use `cd` to enter a folder where you want to do your game development. Here (and in
the rest of the Evennia documentation) we call this folder `mygame`, but you should of course
name your game whatever you like.
evennia --init mygame
This will create a new folder `mygame` (or whatever you chose) in your current location. This
contains empty templates and all the default settings needed to start the server.
## Start the new game
cd mygame
evennia migrate
This will create the default database (Sqlite3). The database file ends up as `mygame/server/evennia.db3`. If you ever want to start from a fresh database, just delete this file and re-run `evennia migrate` again.
evennia start
Set your user-name and password when prompted. This will be the "god user" or "superuser" in-game. The email is optional.
> You can also [automate](./Installation-Non-Interactive.md) the creation of the super user.
If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game!
Log in as a new account or use the superuser you just created.
## Restarting and stopping
You can restart the server without disconnecting players:
evennia restart
To do a full stop and restart (will disconnect players):
evennia reboot
Full stop of the server (use `evennia start` to restart):
evennia stop
## See server logs
Log files are in `mygame/server/logs`. You can tail them live with
evennia --log
or
evennia -l
You can start viewing the log immediately when running `evennia` commands, such as
evennia start -l
To exit the log tailing, enter `Ctrl-C` (`Cmd-C` for Mac). This will not affect the server.
## Server configuration
The server configuration file is `mygame/server/settings.py`. It's empty by default. Copy and change only the settings you want from the [default settings file](./Settings-Default.md).
## Register with the Evennia Game Index (optional)
You can optionally let the world know that you are working on a new Evennia-based game by
registering your server with the _Evennia game index_. You don't have to be
open for players to do this - you just mark your game as closed and "pre-alpha".
evennia connections
See [here](./Evennia-Game-Index.md) for more instructions and please [check out the index](http:games.evennia.com)
beforehand to make sure you don't pick a game name that is already taken - be nice!
## The Next steps
You are good to go!
Next, why not head into the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) to learn how to start making your new game!

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](./Settings.md#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
# This needs to be set to your website address for django or you'll receive a
# CSRF error when trying to log on to the web portal
CSRF_TRUSTED_ORIGINS = ['https://mymudgame.com']
# 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](../Components/Portal-And-Server.md) 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.md) 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.md) (optional)
- [HAProxy Config](./HAProxy-Config.md)
## 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.md#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](https://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](https://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](./Installation-Docker.md) 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 [Setup Quickstart](./Installation.md) 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 rostdev.mushpark.com, 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 "fixed cost" offering.|
| [Azure App Services][12] | Cloud | Free | Free tier with limited regions for hobbyists. |
| [Huawei Cloud][13] | Cloud | on demand | Similar to Amazon. Free 12-month tier with limited regions. |
| [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]: https://silvren.com
[2]: https://www.digitalocean.com/pricing
[3]: https://aws.amazon.com/pricing/
[4]: https://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/
[12]: https://azure.microsoft.com/en-us/pricing/details/app-service/windows/
[13]: https://activity.huaweicloud.com/intl/en-us/free_packages/index.html
## 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](https://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](https://code.google.com/feeds/p/evennia/updates/basic).
## Configuring RSS
To use RSS, you first need to install the [feedparser](https://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.md) to have the feed echo to external chat channels as well.

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.md)
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.

1225
docs/source/Setup/Settings-Default.md Normal file
View file

File diff suppressed because it is too large Load diff

96
docs/source/Setup/Settings.md Normal file
View file

@ -0,0 +1,96 @@
# Game Settings and Configuration direcotry
Evennia runs out of the box without any changes to its settings. But there are several important
ways to customize the server and expand it with your own plugins.
All game-specific settings are located in the `mygame/server/conf/` directory.
## Settings file
The "Settings" file referenced throughout the documentation is the file
`mygame/server/conf/settings.py`.
Your new `settings.py` is relatively bare out of the box. Evennia's core settings file is
the [Settings-Default file](./Settings-Default.md) and is considerably more extensive. It is also
heavily documented and up-to-date, so you should refer to this file directly for the available settings.
Since `mygame/server/conf/settings.py` is a normal Python module, it simply imports
`evennia/settings_default.py` into itself at the top.
This means that if any setting you want to change were to depend on some *other* default setting,
you might need to copy & paste both in order to change them and get the effect you want (for most
commonly changed settings, this is not something you need to worry about).
You should never edit `evennia/settings_default.py`. Rather you should copy&paste the select
variables you want to change into your `settings.py` and edit them there. This will overload the
previously imported defaults.
> Warning: It may be tempting to copy everything from `settings_default.py` into your own settings
file. There is a reason we don't do this out of the box though: it makes it directly clear what
changes you did. Also, if you limit your copying to the things you really need you will directly be
able to take advantage of upstream changes and additions to Evennia for anything you didn't
customize.
In code, the settings is accessed through
```python
from django.conf import settings
# or (shorter):
from evennia import settings
# example:
servername = settings.SERVER_NAME
```
Each setting appears as a property on the imported `settings` object. You can also explore all
possible options with `evennia.settings_full` (this also includes advanced Django defaults that are
not touched in default Evennia).
> When importing `settings` into your code like this, it will be *read
only*. You *cannot* edit your settings from your code! The only way to change an Evennia setting is
to edit `mygame/server/conf/settings.py` directly. You will also need to restart the server
(possibly also the Portal) before a changed setting becomes available.
## Other files in the `server/conf` directory
Apart from the main `settings.py` file,
- `at_initial_setup.py` - this allows you to add a custom startup method to be called (only) the
very first time Evennia starts (at the same time as user #1 and Limbo is created). It can be made to
start your own global scripts or set up other system/world-related things your game needs to have
running from the start.
- `at_server_startstop.py` - this module contains two functions that Evennia will call every time
the Server starts and stops respectively - this includes stopping due to reloading and resetting as
well as shutting down completely. It's a useful place to put custom startup code for handlers and
other things that must run in your game but which has no database persistence.
- `connection_screens.py` - all global string variables in this module are interpreted by Evennia as
a greeting screen to show when an Account first connects. If more than one string variable is
present in the module a random one will be picked.
- `inlinefuncs.py` - this is where you can define custom [FuncParser functions](../Components/FuncParser.md).
- `inputfuncs.py` - this is where you define custom [Input functions](../Components/Inputfuncs.md) to handle data
from the client.
- `lockfuncs.py` - this is one of many possible modules to hold your own "safe" *lock functions* to
make available to Evennia's [Locks](../Components/Locks.md).
- `mssp.py` - this holds meta information about your game. It is used by MUD search engines (which
you often have to register with) in order to display what kind of game you are running along with
statistics such as number of online accounts and online status.
- `oobfuncs.py` - in here you can define custom [OOB functions](../Concepts/OOB.md).
- `portal_services_plugin.py` - this allows for adding your own custom services/protocols to the
Portal. It must define one particular function that will be called by Evennia at startup. There can
be any number of service plugin modules, all will be imported and used if defined. More info can be
found [here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
- `server_services_plugin.py` - this is equivalent to the previous one, but used for adding new
services to the Server instead. More info can be found
[here](https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols).
Some other Evennia systems can be customized by plugin modules but has no explicit template in
`conf/`:
- *cmdparser.py* - a custom module can be used to totally replace Evennia's default command parser.
All this does is to split the incoming string into "command name" and "the rest". It also handles
things like error messages for no-matches and multiple-matches among other things that makes this
more complex than it sounds. The default parser is *very* generic, so you are most often best served
by modifying things further down the line (on the command parse level) than here.
- *at_search.py* - this allows for replacing the way Evennia handles search results. It allows to
change how errors are echoed and how multi-matches are resolved and reported (like how the default
understands that "2-ball" should match the second "ball" object if there are two of them in the
room).

47
docs/source/Setup/Setup-Overview.md Normal file
View file

@ -0,0 +1,47 @@
# Server Setup and Life
This sums up all steps of maintaining your Evennia game from first installation to production release.
## Installation & running
```{toctree}
:maxdepth: 2
Installation
Installation-Git
Installation-Docker
Installation-Troubleshooting
Installation-Android
Installation-Upgrade
Installation-Non-Interactive
Start-Stop-Reload
```
## Configuring
```{toctree}
:maxdepth: 2
Settings
Settings-Default
Choosing-An-SQL-Server
Evennia-Game-Index
IRC
Grapevine
RSS
How-to-connect-Evennia-to-Twitter
Client-Support-Grid
```
## Going public
```{toctree}
:maxdepth: 2
Online-Setup
Security
HAProxy-Config
Apache-Config
```

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

@ -0,0 +1,188 @@
# 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 on the [Installation](./Installation.md) page.
```{sidebar} evennia not found?
If you ever try the `evennia` command and get an error complaining that the command is not available, make sure your [virtualenv](../Glossary.md#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 [Portal and Server](../Components/Portal-And-Server.md). 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`.
## 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](../Components/Scripts.md). 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.
## Stopping
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.
## 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](../Coding/Debugging.md). Next time you `evennia reload` the server, it will return to normal mode.
evennia ipstart
will start the *Portal* in interactive mode.
## 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
## 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 the 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.