Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-03 22:47:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2021-05-16 00:06:01 +02:00
parent 58f5ece91b
commit 1bbc93507a
1000 changed files with 39106 additions and 33861 deletions
Download patch file Download diff file Expand all files Collapse all files

57
docs/1.0-dev/Setup/Apache-Config.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Apache Config &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="apache-config">
<section id="apache-config">
<h1>Apache Config<a class="headerlink" href="#apache-config" title="Permalink to this headline"></a></h1>
<p><strong>Warning</strong>: 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
@ -50,9 +51,9 @@ covered at the end of this page.</p>
<p>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.</p>
<div class="section" id="mod-wsgi-setup">
<section id="mod-wsgi-setup">
<h2><code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> Setup<a class="headerlink" href="#mod-wsgi-setup" title="Permalink to this headline"></a></h2>
<div class="section" id="install-mod-wsgi">
<section id="install-mod-wsgi">
<h3>Install <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code><a class="headerlink" href="#install-mod-wsgi" title="Permalink to this headline"></a></h3>
<ul>
<li><p><em>Fedora/RHEL</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> are available in the standard package
@ -71,15 +72,15 @@ $ apt-get install apache2 libapache2-mod-wsgi
</div>
</li>
</ul>
</div>
<div class="section" id="copy-and-modify-the-vhost">
</section>
<section id="copy-and-modify-the-vhost">
<h3>Copy and modify the VHOST<a class="headerlink" href="#copy-and-modify-the-vhost" title="Permalink to this headline"></a></h3>
<p>After <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is installed, copy the <code class="docutils literal notranslate"><span class="pre">evennia/web/utils/evennia_wsgi_apache.conf</span></code> file to your
apache2 vhosts/sites folder. On Debian/Ubuntu, this is <code class="docutils literal notranslate"><span class="pre">/etc/apache2/sites-enabled/</span></code>. Make your
modifications <strong>after</strong> copying the file there.</p>
<p>Read the comments and change the paths to point to the appropriate locations within your setup.</p>
</div>
<div class="section" id="restart-reload-apache">
</section>
<section id="restart-reload-apache">
<h3>Restart/Reload Apache<a class="headerlink" href="#restart-reload-apache" title="Permalink to this headline"></a></h3>
<p>You’ll then want to reload or restart apache2 after changing the configurations.</p>
<ul>
@ -94,15 +95,15 @@ modifications <strong>after</strong> copying the file there.</p>
</div>
</li>
</ul>
</div>
<div class="section" id="enjoy">
</section>
<section id="enjoy">
<h3>Enjoy<a class="headerlink" href="#enjoy" title="Permalink to this headline"></a></h3>
<p>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 <a class="reference external" href="http://evennia.com">Evennia Community
site</a>.</p>
</div>
<div class="section" id="a-note-on-code-reloading">
</section>
<section id="a-note-on-code-reloading">
<h3>A note on code reloading<a class="headerlink" href="#a-note-on-code-reloading" title="Permalink to this headline"></a></h3>
<p>If your <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is set up to run on daemon mode (as will be the case by default on Debian and
Ubuntu), you may tell <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> to reload by using the <code class="docutils literal notranslate"><span class="pre">touch</span></code> command on
@ -111,8 +112,8 @@ changed, it will force a code reload. Any modifications to the code will not be
live instance of your site until reloaded.</p>
<p>If you are not running in daemon mode or want to force the issue, simply restart or reload apache2
to apply your changes.</p>
</div>
<div class="section" id="further-notes-and-hints">
</section>
<section id="further-notes-and-hints">
<h3>Further notes and hints:<a class="headerlink" href="#further-notes-and-hints" title="Permalink to this headline"></a></h3>
<p>If you get strange (and usually uninformative) <code class="docutils literal notranslate"><span class="pre">Permission</span> <span class="pre">denied</span></code> errors from Apache, make sure
that your <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory is located in a place the webserver may actually access. For example,
@ -126,15 +127,15 @@ Not confirmed, but worth trying if there are trouble.</p>
<span class="o">&lt;/</span><span class="n">Directory</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="mod-proxy-and-mod-ssl-setup">
</section>
</section>
<section id="mod-proxy-and-mod-ssl-setup">
<h2><code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> setup<a class="headerlink" href="#mod-proxy-and-mod-ssl-setup" title="Permalink to this headline"></a></h2>
<p>Below are steps on running Evennia using a front-end proxy (Apache HTTP), <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code>,
<code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code>, and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code>. <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code> will simply be
referred to as
<code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> below.</p>
<div class="section" id="install-mod-ssl">
<section id="install-mod-ssl">
<h3>Install <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code><a class="headerlink" href="#install-mod-ssl" title="Permalink to this headline"></a></h3>
<ul>
<li><p><em>Fedora/RHEL</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> are available in the standard package
@ -156,11 +157,11 @@ $ a2enmod ssl
</div>
</li>
</ul>
</div>
<div class="section" id="tls-proxy-websocket-configuration">
</section>
<section id="tls-proxy-websocket-configuration">
<h3>TLS proxy+websocket configuration<a class="headerlink" href="#tls-proxy-websocket-configuration" title="Permalink to this headline"></a></h3>
<p>Below is a sample configuration for Evennia with a TLS-enabled http and websocket proxy.</p>
<div class="section" id="apache-http-server-configuration">
<section id="apache-http-server-configuration">
<h4>Apache HTTP Server Configuration<a class="headerlink" href="#apache-http-server-configuration" title="Permalink to this headline"></a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>&lt;VirtualHost *:80&gt;
# Always redirect to https/443
@ -195,8 +196,8 @@ $ a2enmod ssl
&lt;/VirtualHost&gt;
</pre></div>
</div>
</div>
<div class="section" id="evennia-secure-websocket-configuration">
</section>
<section id="evennia-secure-websocket-configuration">
<h4>Evennia secure websocket configuration<a class="headerlink" href="#evennia-secure-websocket-configuration" title="Permalink to this headline"></a></h4>
<p>There is a slight trick in setting up Evennia so websocket traffic is handled correctly by the
proxy. You must set the <code class="docutils literal notranslate"><span class="pre">WEBSOCKET_CLIENT_URL</span></code> setting in your <code class="docutils literal notranslate"><span class="pre">mymud/server/conf/settings.py</span></code> file:</p>
@ -204,14 +205,14 @@ proxy. You must set the <code class="docutils literal notranslate"><span class="
</pre></div>
</div>
<p>The setting above is what the client’s browser will actually use. Note the use of <code class="docutils literal notranslate"><span class="pre">wss://</span></code> is
because our client will be communicating over an encrypted connection (“wss” indicates websocket
because our client will be communicating over an encrypted connection (”wss” indicates websocket
over SSL/TLS). Also, especially note the additional path <code class="docutils literal notranslate"><span class="pre">/ws</span></code> 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).</p>
</div>
</div>
</div>
</div>
</section>
</section>
</section>
</section>
<div class="clearer"></div>

159
docs/1.0-dev/Setup/Choosing-An-SQL-Server.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Choosing An SQL Server &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="choosing-an-sql-server">
<section id="choosing-an-sql-server">
<h1>Choosing An SQL Server<a class="headerlink" href="#choosing-an-sql-server" title="Permalink to this headline"></a></h1>
<p>This page gives an overview of the supported SQL databases as well as instructions on install:</p>
<ul class="simple">
@ -49,7 +50,7 @@
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 <a class="reference external" href="http://docs.djangoproject.com/en/dev/ref/databases/#ref-databases">Notes about supported
Databases</a> page.</p>
<div class="section" id="sqlite3">
<section id="sqlite3">
<h2>SQLite3<a class="headerlink" href="#sqlite3" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://sqlite.org/">SQLite3</a> 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
@ -74,7 +75,7 @@ its records. This has to do with file-locking clashes of the database file. So f
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.</p></li>
</ul>
<div class="section" id="install-of-sqlite3">
<section id="install-of-sqlite3">
<h3>Install of SQlite3<a class="headerlink" href="#install-of-sqlite3" title="Permalink to this headline"></a></h3>
<p>This is installed and configured as part of Evennia. The database file is created as
<code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code> when you run</p>
@ -87,23 +88,23 @@ evennia database is <code class="docutils literal notranslate"><span class="pre"
distro while Mac/Windows should get the <a class="reference external" href="https://sqlite.org/download.html">sqlite-tools package from this
page</a>.</p>
<p>To inspect the default Evennia database (once it’s been created), go to your game dir and do</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span> sqlite3 server/evennia.db3
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> sqlite3 server/evennia.db3
<span class="c1"># or </span>
evennia dbshell
</pre></div>
</td></tr></table></div>
<p>This will bring you into the sqlite command line. Use <code class="docutils literal notranslate"><span class="pre">.help</span></code> for instructions and <code class="docutils literal notranslate"><span class="pre">.quit</span></code> to exit.
See <a class="reference external" href="https://gist.github.com/vincent178/10889334">here</a> for a cheat-sheet of commands.</p>
</div>
</div>
<div class="section" id="postgresql">
</section>
</section>
<section id="postgresql">
<h2>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.postgresql.org/">PostgreSQL</a> 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.</p>
<div class="section" id="install-and-initial-setup-of-postgresql">
<section id="install-and-initial-setup-of-postgresql">
<h3>Install and initial setup of PostgreSQL<a class="headerlink" href="#install-and-initial-setup-of-postgresql" title="Permalink to this headline"></a></h3>
<p>First, install the posgresql server. Version <code class="docutils literal notranslate"><span class="pre">9.6</span></code> is tested with Evennia. Packages are readily
available for all distributions. You need to also get the <code class="docutils literal notranslate"><span class="pre">psql</span></code> client (this is called <code class="docutils literal notranslate"><span class="pre">postgresql-</span> <span class="pre">client</span></code> on debian-derived systems). Windows/Mac users can <a class="reference external" href="https://www.postgresql.org/download/">find what they need on the postgresql
@ -111,7 +112,7 @@ download page</a>. You should be setting up a password for your
database-superuser (always called <code class="docutils literal notranslate"><span class="pre">postgres</span></code>) when you install.</p>
<p>For interaction with Evennia you need to also install <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> to your Evennia install (<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2-binary</span></code> in your virtualenv). This acts as the python bridge to the database server.</p>
<p>Next, start the postgres client:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> psql -U postgres --password
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> psql -U postgres --password
</pre></div>
</td></tr></table></div>
<div class="admonition warning">
@ -122,19 +123,19 @@ have to since the resulting command, and your password, will be logged in the sh
</div>
<p>This will open a console to the postgres service using the psql client.</p>
<p>On the psql command line:</p>
<div class="highlight-sql notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">USER</span> <span class="n">evennia</span> <span class="k">WITH</span> <span class="n">PASSWORD</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">;</span>
<div class="highlight-sql notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">USER</span> <span class="n">evennia</span> <span class="k">WITH</span> <span class="n">PASSWORD</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">;</span>
<span class="k">CREATE</span> <span class="k">DATABASE</span> <span class="n">evennia</span><span class="p">;</span>
<span class="c1">-- Postgres-specific optimizations</span>
@ -156,22 +157,22 @@ 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
<code class="docutils literal notranslate"><span class="pre">postgres</span></code> superuser again, then do <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">DATABASE</span> <span class="pre">evennia;</span></code>, then <code class="docutils literal notranslate"><span class="pre">CREATE</span></code> and <code class="docutils literal notranslate"><span class="pre">GRANT</span></code> steps above
again to recreate the database and grant privileges.</p>
</div>
<div class="section" id="evennia-postgresql-configuration">
</section>
<section id="evennia-postgresql-configuration">
<h3>Evennia PostgreSQL configuration<a class="headerlink" href="#evennia-postgresql-configuration" title="Permalink to this headline"></a></h3>
<p>Edit `mygame/server/conf/secret_settings.py and add the following section:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1">#</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1">#</span>
<span class="c1"># PostgreSQL Database Configuration</span>
<span class="c1">#</span>
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
@ -197,8 +198,8 @@ also use</p>
<p>as a shortcut to get into the postgres command line for the right database and user.</p>
<p>With the database setup you should now be able to start start Evennia normally with your new
database.</p>
</div>
<div class="section" id="advanced-postgresql-usage-remote-server">
</section>
<section id="advanced-postgresql-usage-remote-server">
<h3>Advanced Postgresql Usage (Remote Server)<a class="headerlink" href="#advanced-postgresql-usage-remote-server" title="Permalink to this headline"></a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
@ -218,9 +219,9 @@ 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.</p>
<p>First, determine which cluster is running your database. Use <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code>:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ pg_lsclusters
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
<span class="m">12</span> main <span class="m">5432</span> online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
</pre></div>
@ -254,11 +255,11 @@ for more details.)</p>
<p>Finally, modify the <code class="docutils literal notranslate"><span class="pre">pg_hba.conf</span></code> (in the same directory as <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>).
Look for a line with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># IPv4 local connections:</span>
<span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span><span class="o">/</span><span class="mi">32</span> <span class="n">md5</span>
<span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">127.0.0.1</span><span class="o">/</span><span class="mi">32</span> <span class="n">md5</span>
</pre></div>
</div>
<p>Add a line with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span><span class="o">/</span><span class="mi">0</span> <span class="n">md5</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">0.0.0.0</span><span class="o">/</span><span class="mi">0</span> <span class="n">md5</span>
</pre></div>
</div>
<div class="admonition warning">
@ -267,7 +268,7 @@ Look for a line with:</p>
the PosgreSQL documentation on how to limit this.</p>
</div>
<p>Now, restart your cluster:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ pg_ctlcluster <span class="m">12</span> main restart
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ pg_ctlcluster <span class="m">12</span> main restart
</pre></div>
</td></tr></table></div>
<p>Finally, update the database settings in your Evennia secret_settings.py (as
@ -275,14 +276,14 @@ described <a class="reference external" href="#evennia-postgresql-configuration"
<code class="docutils literal notranslate"><span class="pre">PORT</span></code> to match your server.</p>
<p>Now your Evennia installation should be able to connect and talk with a remote
server.</p>
</div>
</div>
<div class="section" id="mysql-mariadb">
</section>
</section>
<section id="mysql-mariadb">
<h2>MySQL / MariaDB<a class="headerlink" href="#mysql-mariadb" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.mysql.com/">MySQL</a> is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called <a class="reference external" href="https://mariadb.org/">MariaDB</a> that mimics
all functionality and command syntax of the former. So this section covers both.</p>
<div class="section" id="installing-and-initial-setup-of-mysql-mariadb">
<section id="installing-and-initial-setup-of-mysql-mariadb">
<h3>Installing and initial setup of MySQL/MariaDB<a class="headerlink" href="#installing-and-initial-setup-of-mysql-mariadb" title="Permalink to this headline"></a></h3>
<p>First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
<code class="docutils literal notranslate"><span class="pre">mysql-server</span></code> or <code class="docutils literal notranslate"><span class="pre">mariadb-server</span></code> packages for their respective distributions. Windows/Mac users
@ -293,19 +294,19 @@ should usually be asked to set up the database root user and password.</p>
<p>You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the <code class="docutils literal notranslate"><span class="pre">mysqlclient</span></code> one. Install this into the evennia virtualenv with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code>.</p>
<p>Start the database client (this is named the same for both mysql and mariadb):</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span>mysql -u root -p
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>mysql -u root -p
</pre></div>
</td></tr></table></div>
<p>You should get to enter your database root password (set this up when you installed the database
server).</p>
<p>Inside the database client interface:</p>
<div class="highlight-sql notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">USER</span> <span class="s1">&#39;evennia&#39;</span><span class="o">@</span><span class="s1">&#39;localhost&#39;</span> <span class="n">IDENTIFIED</span> <span class="k">BY</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">;</span>
<div class="highlight-sql notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">USER</span> <span class="s1">&#39;evennia&#39;</span><span class="o">@</span><span class="s1">&#39;localhost&#39;</span> <span class="n">IDENTIFIED</span> <span class="k">BY</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">;</span>
<span class="k">CREATE</span> <span class="k">DATABASE</span> <span class="n">evennia</span><span class="p">;</span>
<span class="k">ALTER</span> <span class="k">DATABASE</span> <span class="o">`</span><span class="n">evennia</span><span class="o">`</span> <span class="nb">CHARACTER</span> <span class="k">SET</span> <span class="n">utf8</span><span class="p">;</span> <span class="c1">-- note that it&#39;s `evennia` with back-ticks, not</span>
<span class="n">quotes</span><span class="o">!</span>
@ -327,9 +328,9 @@ you can use <code class="docutils literal notranslate"><span class="pre">evennia
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.</p>
</div></blockquote>
</div>
</div>
<div class="section" id="add-mysql-configuration-to-evennia">
</section>
</section>
<section id="add-mysql-configuration-to-evennia">
<h2>Add MySQL configuration to Evennia<a class="headerlink" href="#add-mysql-configuration-to-evennia" title="Permalink to this headline"></a></h2>
<p>To tell Evennia to use your new database you need to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> (or
<code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
@ -339,19 +340,19 @@ formatted file. Evennia users have however found that this leads to problems (se
#1184</a>). To avoid trouble we recommend you simply put the configuration in
your settings as below.</p>
</div></blockquote>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1">#</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1">#</span>
<span class="c1"># MySQL Database Configuration</span>
<span class="c1">#</span>
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
@ -378,14 +379,14 @@ also use</p>
<p>as a shortcut to get into the postgres command line for the right database and user.</p>
<p>With the database setup you should now be able to start start Evennia normally with your new
database.</p>
</div>
<div class="section" id="others">
</section>
<section id="others">
<h2>Others<a class="headerlink" href="#others" title="Permalink to this headline"></a></h2>
<p>No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for <a class="reference external" href="http://code.google.com/p/django-mssql/">MS SQL</a> and possibly a few
others. If you try other databases out, consider expanding this page with instructions.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

23
docs/1.0-dev/Setup/Client-Support-Grid.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Client Support Grid &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,20 +38,20 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="client-support-grid">
<section id="client-support-grid">
<h1>Client Support Grid<a class="headerlink" href="#client-support-grid" title="Permalink to this headline"></a></h1>
<p>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 <a class="reference external" href="https://github.com/evennia/evennia/issues/new/choose">documentation issue</a> for it. Everyone’s encouraged to report their findings.</p>
<div class="section" id="legend">
<section id="legend">
<h2>Legend:<a class="headerlink" href="#legend" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><strong>Name</strong>: The name of the client. Also note if it’s OS-specific.</p></li>
<li><p><strong>Version</strong>: Which version or range of client versions were tested.</p></li>
<li><p><strong>Comments</strong>: Any quirks on using this client with Evennia should be added here.</p></li>
</ul>
</div>
<div class="section" id="client-grid">
</section>
<section id="client-grid">
<h2>Client Grid<a class="headerlink" href="#client-grid" title="Permalink to this headline"></a></h2>
<table class="docutils align-default">
<colgroup>
@ -159,10 +160,10 @@ the <cite>version</cite> command on connection, which will not work in
</tr>
</tbody>
</table>
</div>
<div class="section" id="workarounds-for-client-issues">
</section>
<section id="workarounds-for-client-issues">
<h2>Workarounds for client issues:<a class="headerlink" href="#workarounds-for-client-issues" title="Permalink to this headline"></a></h2>
<div class="section" id="issue-telnet-nop-displays-as-spurious-character">
<section id="issue-telnet-nop-displays-as-spurious-character">
<h3>Issue: Telnet NOP displays as spurious character.<a class="headerlink" href="#issue-telnet-nop-displays-as-spurious-character" title="Permalink to this headline"></a></h3>
<p>Known clients:</p>
<ul class="simple">
@ -175,9 +176,9 @@ the <cite>version</cite> command on connection, which will not work in
parameter to disable it for that Evennia account permanently.</p></li>
<li><p>Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client.</p></li>
</ul>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>

55
docs/1.0-dev/Setup/Evennia-Game-Index.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Evennia Game Index &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="evennia-game-index">
<section id="evennia-game-index">
<h1>Evennia Game Index<a class="headerlink" href="#evennia-game-index" title="Permalink to this headline"></a></h1>
<p>The <a class="reference external" href="http://games.evennia.com">Evennia game index</a> is a list of games built or
being built with Evennia. Anyone is allowed to add their game to the index</p>
@ -48,7 +49,7 @@ intrigued about or excited for your upcoming game!</p></li>
</ul>
<p>All we ask is that you check so your game-name does not collide with one
already in the list - be nice!</p>
<div class="section" id="connect-with-the-wizard">
<section id="connect-with-the-wizard">
<h2>Connect with the wizard<a class="headerlink" href="#connect-with-the-wizard" title="Permalink to this headline"></a></h2>
<p>From your game dir, run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">connections</span>
@ -65,30 +66,30 @@ 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.</p>
</div></blockquote>
</div>
<div class="section" id="manual-settings">
</section>
<section id="manual-settings">
<h2>Manual Settings<a class="headerlink" href="#manual-settings" title="Permalink to this headline"></a></h2>
<p>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
(<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>). Add the following:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">GAME_INDEX_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">GAME_INDEX_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">GAME_INDEX_LISTING</span> <span class="o">=</span> <span class="p">{</span>
<span class="c1"># required </span>
@ -114,16 +115,16 @@ last resort if we need to get in touch with you over any listing issue/bug (so
far this has never happened).</p>
<p>If <code class="docutils literal notranslate"><span class="pre">game_name</span></code> is not set, the <code class="docutils literal notranslate"><span class="pre">settings.SERVERNAME</span></code> will be used. Use empty strings
(<code class="docutils literal notranslate"><span class="pre">''</span></code>) for optional fields you don’t want to specify at this time.</p>
</div>
<div class="section" id="non-public-games">
</section>
<section id="non-public-games">
<h2>Non-public games<a class="headerlink" href="#non-public-games" title="Permalink to this headline"></a></h2>
<p>If you don’t specify neither <code class="docutils literal notranslate"><span class="pre">telnet_hostname</span> <span class="pre">+</span> <span class="pre">port</span></code> nor
<code class="docutils literal notranslate"><span class="pre">web_client_url</span></code>, the Game index will list your game as <em>Not yet public</em>.
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.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

67
docs/1.0-dev/Setup/Extended-Installation.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Getting Started &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="getting-started">
<section id="getting-started">
<h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline"></a></h1>
<p>This will help you download, install and start Evennia for the first time.</p>
<blockquote>
@ -56,7 +57,7 @@ internet connection until you feel ready to share your game with the world.</p>
<li><p><a class="reference external" href="Setup/Getting-Started#troubleshooting">Troubleshooting</a></p></li>
<li><p><a class="reference internal" href="../Glossary.html"><span class="doc">Glossary of terms</span></a></p></li>
</ul>
<div class="section" id="quick-start">
<section id="quick-start">
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline"></a></h2>
<p>For the impatient. If you have trouble with a step, you should jump on to the
more detailed instructions for your platform.</p>
@ -64,8 +65,8 @@ more detailed instructions for your platform.</p>
<li><p>Install Python, GIT and python-virtualenv. Start a Console/Terminal.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to some place you want to do your development (like a folder
<code class="docutils literal notranslate"><span class="pre">/home/anna/muddev/</span></code> on Linux or a folder in your personal user directory on Windows).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/evennia/evennia.git</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">virtualenv</span> <span class="pre">evenv</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/evennia/evennia.git</span></code> (a new folder <code class="docutils literal notranslate"><span class="pre">evennia</span></code> is created)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">venv</span> <span class="pre">evenv</span></code> (a new folder <code class="docutils literal notranslate"><span class="pre">evenv</span></code> is created)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">source</span> <span class="pre">evenv/bin/activate</span></code> (Linux, Mac), <code class="docutils literal notranslate"><span class="pre">evenv\Scripts\activate</span></code> (Windows)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">evennia</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span> <span class="pre">mygame</span></code></p></li>
@ -78,8 +79,8 @@ not recognize <code class="docutils literal notranslate"><span class="pre">local
</ol>
<p>We also release <a class="reference internal" href="Running-Evennia-in-Docker.html"><span class="doc">Docker images</span></a>
based on <code class="docutils literal notranslate"><span class="pre">master</span></code> and <code class="docutils literal notranslate"><span class="pre">develop</span></code> branches.</p>
</div>
<div class="section" id="requirements">
</section>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<p>Any system that supports Python3.7+ should work. We’ll describe how to install
everything in the following sections.</p>
@ -87,7 +88,7 @@ everything in the following sections.</p>
<li><p>Linux/Unix</p></li>
<li><p>Windows (Vista, Win7, Win8, Win10)</p></li>
<li><p>Mac OSX (&gt;=10.5 recommended)</p></li>
<li><p><a class="reference external" href="http://www.python.org">Python</a> (v3.7, 3.8 are tested)</p>
<li><p><a class="reference external" href="http://www.python.org">Python</a> (v3.7, 3.8 and 3.9 are tested)</p>
<ul>
<li><p><a class="reference external" href="http://pypi.python.org/pypi/virtualenv">virtualenv</a> for making isolated
Python environments. Installed with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">virtualenv</span></code>.</p></li>
@ -109,8 +110,8 @@ Twisted packages</p></li>
<li><p><a class="reference external" href="http://www.djangoproject.com">Django</a> (v2.2.x), be warned that latest dev
version is usually untested with Evennia)</p></li>
</ul>
</div>
<div class="section" id="linux-install">
</section>
<section id="linux-install">
<h2>Linux Install<a class="headerlink" href="#linux-install" title="Permalink to this headline"></a></h2>
<p>If you run into any issues during the installation and first start, please
check out <a class="reference external" href="Setup/Getting-Started#linux-troubleshooting">Linux Troubleshooting</a>.</p>
@ -122,7 +123,7 @@ install the <a class="reference external" href="Setup/Getting-Started#requiremen
<span class="c1"># If you are using an Ubuntu version that defaults to Python3, like 18.04+, use this instead:</span>
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">update</span>
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">python3</span><span class="o">.</span><span class="mi">7</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">.</span><span class="mi">7</span><span class="o">-</span><span class="n">dev</span> <span class="n">python3</span><span class="o">-</span><span class="n">setuptools</span> <span class="n">virtualenv</span> <span class="n">gcc</span>
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">python3</span><span class="mf">.7</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="mf">.7</span><span class="o">-</span><span class="n">dev</span> <span class="n">python3</span><span class="o">-</span><span class="n">setuptools</span> <span class="n">virtualenv</span> <span class="n">gcc</span>
</pre></div>
</div>
<p>Note that, the default Python version for your distribution may still not be Python3.7 after this.
@ -148,9 +149,9 @@ virtualenv</a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># If your Linux defaults to Python3.7+:</span>
<span class="n">virtualenv</span> <span class="n">evenv</span>
<span class="c1"># If your Linux defaults to Python2 or an older version </span>
<span class="c1"># If your Linux defaults to Python2 or an older version</span>
<span class="c1"># of Python3, you must instead point to Python3.7+ explicitly:</span>
<span class="n">virtualenv</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">python3</span><span class="o">.</span><span class="mi">7</span> <span class="n">evenv</span>
<span class="n">virtualenv</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">python3</span><span class="mf">.7</span> <span class="n">evenv</span>
</pre></div>
</div>
<p>A new folder <code class="docutils literal notranslate"><span class="pre">evenv</span></code> will appear (we could have called it anything). This
@ -203,8 +204,8 @@ live in the terminal, use <code class="docutils literal notranslate"><span class
<p>Your game should now be running! Open a web browser at <code class="docutils literal notranslate"><span class="pre">http://localhost:4001</span></code>
or point a telnet client to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code> and log in with the user you
created. Check out <a class="reference external" href="Setup/Getting-Started#where-to-go-next">where to go next</a>.</p>
</div>
<div class="section" id="mac-install">
</section>
<section id="mac-install">
<h2>Mac Install<a class="headerlink" href="#mac-install" title="Permalink to this headline"></a></h2>
<p>The Evennia server is a terminal program. Open the terminal e.g. from
<em>Applications-&gt;Utilities-&gt;Terminal</em>. <a class="reference external" href="http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line">Here is an introduction to the Mac
@ -242,7 +243,7 @@ virtualenv is and why it’s useful, see the <a class="reference external" href=
<span class="n">virtualenv</span> <span class="n">evenv</span>
<span class="c1"># If your Mac defaults to Python2 you need to specify the Python3.7 binary explicitly:</span>
<span class="n">virtualenv</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">python3</span><span class="o">.</span><span class="mi">7</span> <span class="n">evenv</span>
<span class="n">virtualenv</span> <span class="o">-</span><span class="n">p</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">python3</span><span class="mf">.7</span> <span class="n">evenv</span>
</pre></div>
</div>
<p>A new folder <code class="docutils literal notranslate"><span class="pre">evenv</span></code> will appear (we could have called it anything). This
@ -295,8 +296,8 @@ live in the terminal, use <code class="docutils literal notranslate"><span class
<p>Your game should now be running! Open a web browser at <code class="docutils literal notranslate"><span class="pre">http://localhost:4001</span></code>
or point a telnet client to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code> and log in with the user you
created. Check out <a class="reference external" href="Setup/Getting-Started#where-to-go-next">where to go next</a>.</p>
</div>
<div class="section" id="windows-install">
</section>
<section id="windows-install">
<h2>Windows Install<a class="headerlink" href="#windows-install" title="Permalink to this headline"></a></h2>
<p>If you run into any issues during the installation, please check out
<a class="reference external" href="Setup/Getting-Started#windows-troubleshooting">Windows Troubleshooting</a>.</p>
@ -420,8 +421,8 @@ live in the terminal, use <code class="docutils literal notranslate"><span class
<p>Your game should now be running! Open a web browser at <code class="docutils literal notranslate"><span class="pre">http://localhost:4001</span></code>
or point a telnet client to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code> and log in with the user you
created. Check out <a class="reference external" href="Setup/Getting-Started#where-to-go-next">where to go next</a>.</p>
</div>
<div class="section" id="non-interactive-setup">
</section>
<section id="non-interactive-setup">
<h2>Non-interactive setup<a class="headerlink" href="#non-interactive-setup" title="Permalink to this headline"></a></h2>
<p>When you first run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code> after having created the database, you will be asked
to interactively insert the superuser username, email and password. If you need to do
@ -430,11 +431,11 @@ values as environment variables, <code class="docutils literal notranslate"><spa
<code class="docutils literal notranslate"><span class="pre">EVENNIA_SUPERUSER_PASSWORD</span></code>. The email can be left out and will then be set to be the
empty string.</p>
<p>Use this to start Evennia (the envvars will be ignored on subsequent starts):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EVENNIA_SUPERUSER_USERNAME</span><span class="o">=</span><span class="n">Foo</span> <span class="n">EVENNIA_SUPERUSER_PASSWORD</span><span class="o">=</span><span class="n">MygreatPwd</span> <span class="n">evennia</span> <span class="n">start</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EVENNIA_SUPERUSER_USERNAME</span><span class="o">=</span><span class="n">Foo</span> <span class="n">EVENNIA_SUPERUSER_PASSWORD</span><span class="o">=</span><span class="n">MygreatPwd</span> <span class="n">evennia</span> <span class="n">start</span>
</pre></div>
</div>
</div>
<div class="section" id="where-to-go-next">
</section>
<section id="where-to-go-next">
<h2>Where to Go Next<a class="headerlink" href="#where-to-go-next" title="Permalink to this headline"></a></h2>
<p>Welcome to Evennia! Your new game is fully functioning, but empty. If you just
logged in, stand in the <code class="docutils literal notranslate"><span class="pre">Limbo</span></code> room and run</p>
@ -464,8 +465,8 @@ Server</a>.</p>
<p>Finally, if you are itching to help out or support Evennia (awesome!) have an
issue to report or a feature to request, <a class="reference internal" href="../How-To-Get-And-Give-Help.html"><span class="doc">see here</span></a>.</p>
<p>Enjoy your stay!</p>
</div>
<div class="section" id="troubleshooting">
</section>
<section id="troubleshooting">
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h2>
<p>If you have issues with installing or starting Evennia for the first time,
check the section for your operating system below. If you have an issue not
@ -473,7 +474,7 @@ covered here, <a class="reference external" href="https://github.com/evennia/eve
so it can be fixed or a workaround found!</p>
<p>Remember, the server logs are in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>. To easily view server logs in the terminal,
you can run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">-l</span></code>, or (in the future) start the server with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span> <span class="pre">-l</span></code>.</p>
<div class="section" id="linux-troubleshooting">
<section id="linux-troubleshooting">
<h3>Linux Troubleshooting<a class="headerlink" href="#linux-troubleshooting" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p>If you get an error when installing Evennia (especially with lines mentioning
@ -493,8 +494,8 @@ install the <code class="docutils literal notranslate"><span class="pre">redhat-
with symlinks not being supported. Answer is to not use NTFS (seriously, why would you do that to
yourself?)</p></li>
</ul>
</div>
<div class="section" id="mac-troubleshooting">
</section>
<section id="mac-troubleshooting">
<h3>Mac Troubleshooting<a class="headerlink" href="#mac-troubleshooting" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p>Mac users have reported a critical <code class="docutils literal notranslate"><span class="pre">MemoryError</span></code> when trying to start Evennia on Mac with a Python
@ -503,8 +504,8 @@ version below <code class="docutils literal notranslate"><span class="pre">2.7.1
so, try to connect to <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code> instead, which is the same thing. Use port 4000 from mud clients
and port 4001 from the web browser as usual.</p></li>
</ul>
</div>
<div class="section" id="windows-troubleshooting">
</section>
<section id="windows-troubleshooting">
<h3>Windows Troubleshooting<a class="headerlink" href="#windows-troubleshooting" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p>If you installed Python but the <code class="docutils literal notranslate"><span class="pre">python</span></code> command is not available (even in a new console), then
@ -528,9 +529,9 @@ text editor like Notepad. It’s just one line containing the path to the <code
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.</p></li>
</ul>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>

21
docs/1.0-dev/Setup/Grapevine.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Grapevine &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,12 +38,12 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="grapevine">
<section id="grapevine">
<h1>Grapevine<a class="headerlink" href="#grapevine" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="http://grapevine.haus">Grapevine</a> is a new chat network for <code class="docutils literal notranslate"><span class="pre">MU*</span></code>*** 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.</p>
<div class="section" id="configuring-grapevine">
<section id="configuring-grapevine">
<h2>Configuring Grapevine<a class="headerlink" href="#configuring-grapevine" title="Permalink to this headline"></a></h2>
<p>To use Grapevine, you first need the <code class="docutils literal notranslate"><span class="pre">pyopenssl</span></code> module. Install it into your
Evennia python environment with</p>
@ -50,7 +51,7 @@ Evennia python environment with</p>
</pre></div>
</div>
<p>To configure Grapevine, you’ll need to activate it in your settings file.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">GRAPEVINE_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">GRAPEVINE_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</td></tr></table></div>
<p>Next, register an account at https://grapevine.haus. When you have logged in,
@ -58,8 +59,8 @@ go to your Settings/Profile and to the <code class="docutils literal notranslate
new game by filling in its information. At the end of registration you are going
to get a <code class="docutils literal notranslate"><span class="pre">Client</span> <span class="pre">ID</span></code> and a <code class="docutils literal notranslate"><span class="pre">Client</span> <span class="pre">Secret</span></code>. These should not be shared.</p>
<p>Open/create the file <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/secret_settings.py</span></code> and add the following:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">GRAPEVINE_CLIENT_ID</span> <span class="o">=</span> <span class="s2">&quot;&lt;client ID&gt;&quot;</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">GRAPEVINE_CLIENT_ID</span> <span class="o">=</span> <span class="s2">&quot;&lt;client ID&gt;&quot;</span>
<span class="n">GRAPEVINE_CLIENT_SECRET</span> <span class="o">=</span> <span class="s2">&quot;&lt;client_secret&gt;&quot;</span>
</pre></div>
</td></tr></table></div>
@ -78,8 +79,8 @@ command available: <code class="docutils literal notranslate"><span class="pre">
<code class="docutils literal notranslate"><span class="pre">testing</span></code> and <code class="docutils literal notranslate"><span class="pre">gossip</span></code>. Evennia defaults to allowing connecting to both. Use
<code class="docutils literal notranslate"><span class="pre">testing</span></code> for trying your connection.</p>
</div></blockquote>
</div>
<div class="section" id="setting-up-grapevine-step-by-step">
</section>
<section id="setting-up-grapevine-step-by-step">
<h2>Setting up Grapevine, step by step<a class="headerlink" href="#setting-up-grapevine-step-by-step" title="Permalink to this headline"></a></h2>
<p>You can connect Grapevine to any Evennia channel (so you could connect it to
the default <em>public</em> channel if you like), but for testing, let’s set up a
@ -98,8 +99,8 @@ to https://grapevine.haus/chat to check.</p>
the Grapevine chat. Write a reply in the chat and the grapevine bot should echo
it to your channel in-game.</p>
<p>Your Evennia gamers can now chat with users on external Grapevine channels!</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

15
docs/1.0-dev/Setup/HAProxy-Config.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>HAProxy Config (Optional) &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,9 +38,9 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="haproxy-config-optional">
<section id="haproxy-config-optional">
<h1>HAProxy Config (Optional)<a class="headerlink" href="#haproxy-config-optional" title="Permalink to this headline"></a></h1>
<div class="section" id="evennia-https-and-secure-websockets-can-play-nicely-together-quickly">
<section id="evennia-https-and-secure-websockets-can-play-nicely-together-quickly">
<h2>Evennia, HTTPS and Secure Websockets can play nicely together, quickly.<a class="headerlink" href="#evennia-https-and-secure-websockets-can-play-nicely-together-quickly" title="Permalink to this headline"></a></h2>
<p>This sets up HAProxy 1.5+ in front of Evennia to provide security.</p>
<p>Installing HAProxy is usually as simple as:</p>
@ -72,12 +73,12 @@
<span class="n">listen</span> <span class="n">evennia</span><span class="o">-</span><span class="n">https</span><span class="o">-</span><span class="n">website</span>
<span class="n">bind</span> <span class="o">&lt;</span><span class="n">public</span><span class="o">-</span><span class="n">ip</span><span class="o">-</span><span class="n">address</span><span class="o">&gt;</span><span class="p">:</span><span class="o">&lt;</span><span class="n">public</span><span class="o">-</span><span class="n">SSL</span><span class="o">-</span><span class="n">port</span><span class="o">--</span><span class="n">probably</span><span class="o">-</span><span class="mi">443</span><span class="o">&gt;</span> <span class="n">ssl</span> <span class="n">no</span><span class="o">-</span><span class="n">sslv3</span> <span class="n">no</span><span class="o">-</span><span class="n">tlsv10</span> <span class="n">crt</span>
<span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">-</span><span class="n">cert</span><span class="o">.</span><span class="n">pem</span>
<span class="n">server</span> <span class="n">localhost</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span><span class="p">:</span><span class="o">&lt;</span><span class="n">evennia</span><span class="o">-</span><span class="n">web</span><span class="o">-</span><span class="n">port</span><span class="o">-</span><span class="n">probably</span><span class="o">-</span><span class="mi">4001</span><span class="o">&gt;</span>
<span class="n">server</span> <span class="n">localhost</span> <span class="mf">127.0.0.1</span><span class="p">:</span><span class="o">&lt;</span><span class="n">evennia</span><span class="o">-</span><span class="n">web</span><span class="o">-</span><span class="n">port</span><span class="o">-</span><span class="n">probably</span><span class="o">-</span><span class="mi">4001</span><span class="o">&gt;</span>
<span class="n">listen</span> <span class="n">evennia</span><span class="o">-</span><span class="n">secure</span><span class="o">-</span><span class="n">websocket</span>
<span class="n">bind</span> <span class="o">&lt;</span><span class="n">public</span><span class="o">-</span><span class="n">ip</span><span class="o">-</span><span class="n">address</span><span class="o">&gt;</span><span class="p">:</span><span class="o">&lt;</span><span class="n">WEBSOCKET_CLIENT_URL</span> <span class="mi">4002</span><span class="o">&gt;</span> <span class="n">ssl</span> <span class="n">no</span><span class="o">-</span><span class="n">sslv3</span> <span class="n">no</span><span class="o">-</span><span class="n">tlsv10</span> <span class="n">crt</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">-</span>
<span class="n">cert</span><span class="o">.</span><span class="n">pem</span>
<span class="n">server</span> <span class="n">localhost</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span><span class="p">:</span><span class="o">&lt;</span><span class="n">WEBSOCKET_CLIENT_URL</span> <span class="mi">4002</span><span class="o">&gt;</span>
<span class="n">server</span> <span class="n">localhost</span> <span class="mf">127.0.0.1</span><span class="p">:</span><span class="o">&lt;</span><span class="n">WEBSOCKET_CLIENT_URL</span> <span class="mi">4002</span><span class="o">&gt;</span>
<span class="n">timeout</span> <span class="n">client</span> <span class="mi">10</span><span class="n">m</span>
<span class="n">timeout</span> <span class="n">server</span> <span class="mi">10</span><span class="n">m</span>
</pre></div>
@ -95,8 +96,8 @@
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">WEBSOCKET_CLIENT_URL</span><span class="o">=</span><span class="s2">&quot;wss://yourhost.com:4002/&quot;</span>
</pre></div>
</div>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

111
docs/1.0-dev/Setup/How-to-connect-Evennia-to-Twitter.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>How to connect Evennia to Twitter &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,12 +38,12 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="how-to-connect-evennia-to-twitter">
<section id="how-to-connect-evennia-to-twitter">
<h1>How to connect Evennia to Twitter<a class="headerlink" href="#how-to-connect-evennia-to-twitter" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="http://en.wikipedia.org/wiki/twitter">Twitter</a> 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.</p>
<div class="section" id="configuring-twitter">
<section id="configuring-twitter">
<h2>Configuring Twitter<a class="headerlink" href="#configuring-twitter" title="Permalink to this headline"></a></h2>
<p>You must first have a Twitter account. Log in and register an App at the <a class="reference external" href="https://apps.twitter.com/">Twitter Dev
Site</a>. Make sure you enable access to “write” tweets!</p>
@ -52,15 +53,15 @@ Site</a>. Make sure you enable access to “write” tweets!</p>
apps with write access. If you’re unable to do this, please see <a class="reference external" href="https://dev.twitter.com/notifications/new-apps-registration">this Dev
post</a> which describes how to get around
it.</p>
</div>
<div class="section" id="install-the-twitter-python-module">
</section>
<section id="install-the-twitter-python-module">
<h2>Install the twitter python module<a class="headerlink" href="#install-the-twitter-python-module" title="Permalink to this headline"></a></h2>
<p>To use Twitter you must install the <a class="reference external" href="https://pypi.python.org/pypi/twitter">Twitter</a> Python module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">twitter</span>
</pre></div>
</div>
</div>
<div class="section" id="a-basic-tweet-command">
</section>
<section id="a-basic-tweet-command">
<h2>A basic tweet command<a class="headerlink" href="#a-basic-tweet-command" title="Permalink to this headline"></a></h2>
<p>Evennia doesn’t have a <code class="docutils literal notranslate"><span class="pre">tweet</span></code> command out of the box so you need to write your own little
<a class="reference internal" href="../Components/Commands.html"><span class="doc">Command</span></a> in order to tweet. If you are unsure about how commands work and how to add
@ -69,50 +70,50 @@ before continuing.</p>
<p>You can create the command in a separate command module (something like <code class="docutils literal notranslate"><span class="pre">mygame/commands/tweet.py</span></code>)
or together with your other custom commands, as you prefer.</p>
<p>This is how it can look:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">twitter</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span>
<span class="normal">24</span>
<span class="normal">25</span>
<span class="normal">26</span>
<span class="normal">27</span>
<span class="normal">28</span>
<span class="normal">29</span>
<span class="normal">30</span>
<span class="normal">31</span>
<span class="normal">32</span>
<span class="normal">33</span>
<span class="normal">34</span>
<span class="normal">35</span>
<span class="normal">36</span>
<span class="normal">37</span>
<span class="normal">38</span>
<span class="normal">39</span>
<span class="normal">40</span>
<span class="normal">41</span>
<span class="normal">42</span>
<span class="normal">43</span>
<span class="normal">44</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">twitter</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">Command</span>
<span class="c1"># here you insert your unique App tokens</span>
@ -165,8 +166,8 @@ permission to <code class="docutils literal notranslate"><span class="pre">Playe
<p>Now add this command to your default command set (e.g in <code class="docutils literal notranslate"><span class="pre">mygame/commands/defalt_cmdsets.py</span></code>”) and
reload the server. From now on those with access can simply use <code class="docutils literal notranslate"><span class="pre">tweet</span> <span class="pre">&lt;message&gt;</span></code> to see the tweet
posted from the game’s Twitter account.</p>
</div>
<div class="section" id="next-steps">
</section>
<section id="next-steps">
<h2>Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline"></a></h2>
<p>This shows only a basic tweet setup, other things to do could be:</p>
<ul class="simple">
@ -178,8 +179,8 @@ posted from the game’s Twitter account.</p>
<p>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 <a class="reference internal" href="../Howto/Tutorial-Tweeting-Game-Stats.html"><span class="doc">Tweeting Game Stats tutorial</span></a> for
help.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

17
docs/1.0-dev/Setup/IRC.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>IRC &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="irc">
<section id="irc">
<h1>IRC<a class="headerlink" href="#irc" title="Permalink to this headline"></a></h1>
<p><em>Disambiguation: This page is related to using IRC inside an Evennia game. To join the official
Evennia IRC chat, connect to irc.freenode.net and join #evennia. Alternatively, you can <a class="reference external" href="https://discord.gg/NecFePw">join our
@ -50,10 +51,10 @@ computer (your game doesn’t need to be open to the public)! All you need is an
For IRC operation you also need <a class="reference external" href="http://twistedmatrix.com/trac/wiki/TwistedWords">twisted.words</a>.
This is available simply as a package <em>python-twisted-words</em> in many Linux distros, or directly
downloadable from the link.</p>
<div class="section" id="configuring-irc">
<section id="configuring-irc">
<h2>Configuring IRC<a class="headerlink" href="#configuring-irc" title="Permalink to this headline"></a></h2>
<p>To configure IRC, you’ll need to activate it in your settings file.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">IRC_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">IRC_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</td></tr></table></div>
<p>Start Evennia and log in as a privileged user. You should now have a new command available:
@ -63,8 +64,8 @@ downloadable from the link.</p>
</div>
<p>If you already know how IRC works, this should be pretty self-evident to use. Read the help entry
for more features.</p>
</div>
<div class="section" id="setting-up-irc-step-by-step">
</section>
<section id="setting-up-irc-step-by-step">
<h2>Setting up IRC, step by step<a class="headerlink" href="#setting-up-irc-step-by-step" title="Permalink to this headline"></a></h2>
<p>You can connect IRC to any Evennia channel (so you could connect it to the default <em>public</em> channel
if you like), but for testing, let’s set up a new channel <code class="docutils literal notranslate"><span class="pre">irc</span></code>.</p>
@ -116,8 +117,8 @@ name of the IRC channel you used (#evennia here).</p>
</pre></div>
</div>
<p>Your Evennia gamers can now chat with users on external IRC channels!</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

35
docs/1.0-dev/Setup/Installing-on-Android.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installing on Android &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,12 +38,12 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="installing-on-android">
<section id="installing-on-android">
<h1>Installing on Android<a class="headerlink" href="#installing-on-android" title="Permalink to this headline"></a></h1>
<p>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.</p>
<div class="section" id="install-termux">
<section id="install-termux">
<h2>Install Termux<a class="headerlink" href="#install-termux" title="Permalink to this headline"></a></h2>
<p>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
@ -59,8 +60,8 @@ prerequisites for Evennia. Commands you should run in Termux will look like this
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">$</span></code> symbol is your prompt - do not include it when running commands.</p>
</div>
<div class="section" id="prerequisites">
</section>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h2>
<p>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</p>
@ -89,7 +90,7 @@ following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">pip</span> <span class="n">setuptools</span> <span class="n">wheel</span>
</pre></div>
</div>
<div class="section" id="installing-evennia">
<section id="installing-evennia">
<h3>Installing Evennia<a class="headerlink" href="#installing-evennia" title="Permalink to this headline"></a></h3>
<p>Now that we have everything in place, we’re ready to download and install Evennia itself.</p>
<p>Mysterious incantations</p>
@ -106,8 +107,8 @@ following command:</p>
building all of the requirements for Evennia to run. If you run into trouble on this step, please
see <a class="reference external" href="Setup/Installing-on-Android.html#troubleshooting">Troubleshooting</a>.</p>
<p>You can go to the dir where Evennia is installed with <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">$VIRTUAL_ENV/src/evennia</span></code>. <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">grep</span> <span class="pre">(something)</span></code> can be handy, as can <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span></code></p>
</div>
<div class="section" id="final-steps">
</section>
<section id="final-steps">
<h3>Final steps<a class="headerlink" href="#final-steps" title="Permalink to this headline"></a></h3>
<p>At this point, Evennia is installed on your phone! You can now continue with the original
<a class="reference internal" href="Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a> instruction, we repeat them here for clarity.</p>
@ -125,9 +126,9 @@ mygame evenv
</div>
<p>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.</p>
</div>
</div>
<div class="section" id="running-evennia">
</section>
</section>
<section id="running-evennia">
<h2>Running Evennia<a class="headerlink" href="#running-evennia" title="Permalink to this headline"></a></h2>
<p>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.</p>
@ -137,8 +138,8 @@ virtualenv as well as are in your game’s directory. You can then run evennia s
</pre></div>
</div>
<p>You may wish to look at the <a class="reference external" href="Setup/Getting-Started#linux-install">Linux Instructions</a> for more.</p>
</div>
<div class="section" id="caveats">
</section>
<section id="caveats">
<h2>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>Android’s os module doesn’t support certain functions - in particular getloadavg. Thusly, running
@ -147,8 +148,8 @@ the command &#64;server in-game will throw an exception. So far, there is no fix
<li><p>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.</p></li>
</ul>
</div>
<div class="section" id="troubleshooting">
</section>
<section id="troubleshooting">
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h2>
<p>As time goes by and errors are reported, this section will be added to.</p>
<p>Some steps to try anyway:</p>
@ -160,8 +161,8 @@ killed if your phone is heavily taxed. Termux seems to keep a notification up to
<li><p>See if a shell will start: <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">~/mygame</span> <span class="pre">;</span> <span class="pre">evennia</span> <span class="pre">shell</span></code></p></li>
<li><p>Look at the log files in ~/mygame/server/logs/</p></li>
</ul>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

203
docs/1.0-dev/Setup/Online-Setup.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Online Setup &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,12 +38,12 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="online-setup">
<section id="online-setup">
<h1>Online Setup<a class="headerlink" href="#online-setup" title="Permalink to this headline"></a></h1>
<p>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.</p>
<div class="section" id="connecting-from-the-outside">
<section id="connecting-from-the-outside">
<h2>Connecting from the outside<a class="headerlink" href="#connecting-from-the-outside" title="Permalink to this headline"></a></h2>
<p>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
@ -103,7 +104,7 @@ requests use and web browsers automatically look for - if you do that you could
<code class="docutils literal notranslate"><span class="pre">http://203.0.113.0</span></code> without having to add the port at the end. This would collide with any other
web services you are running through this router though.</p>
</div></blockquote>
<div class="section" id="settings-example">
<section id="settings-example">
<h3>Settings example<a class="headerlink" href="#settings-example" title="Permalink to this headline"></a></h3>
<p>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
@ -112,25 +113,25 @@ to do a full <code class="docutils literal notranslate"><span class="pre">evenni
<p>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 <code class="docutils literal notranslate"><span class="pre">203.0.113.0</span></code>.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># in mygame/server/conf/settings.py</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># in mygame/server/conf/settings.py</span>
<span class="n">SERVERNAME</span> <span class="o">=</span> <span class="s2">&quot;MyGame&quot;</span>
@ -152,17 +153,17 @@ continue to assume that our server address is <code class="docutils literal notr
</pre></div>
</td></tr></table></div>
<p>Read on for a description of the individual settings.</p>
</div>
<div class="section" id="telnet">
</section>
<section id="telnet">
<h3>Telnet<a class="headerlink" href="#telnet" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. Change to whichever outgoing Telnet port(s) </span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span>
<span class="normal">8</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. Change to whichever outgoing Telnet port(s) </span>
<span class="c1"># you are allowed to use on your host.</span>
<span class="n">TELNET_PORTS</span> <span class="o">=</span> <span class="p">[</span><span class="mi">4000</span><span class="p">]</span>
<span class="c1"># Optional for security. Restrict which telnet </span>
@ -175,23 +176,23 @@ continue to assume that our server address is <code class="docutils literal notr
<p>The <code class="docutils literal notranslate"><span class="pre">TELNET_*</span></code> 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.</p>
</div>
<div class="section" id="web-server">
</section>
<section id="web-server">
<h3>Web server<a class="headerlink" href="#web-server" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. This is a list of tuples </span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. This is a list of tuples </span>
<span class="c1"># (outgoing_port, internal_port). Only the outgoing</span>
<span class="c1"># port should be open to the world! </span>
<span class="c1"># set outgoing port to 80 if you want to run Evennia</span>
@ -214,20 +215,20 @@ any other web server on the machine.
The <em>internal</em> port (<code class="docutils literal notranslate"><span class="pre">4005</span></code> 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.</p>
</div>
<div class="section" id="web-client">
</section>
<section id="web-client">
<h3>Web client<a class="headerlink" href="#web-client" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. Change this to the main IP address of your server.</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Required. Change this to the main IP address of your server.</span>
<span class="n">WEBSOCKET_CLIENT_INTERFACE</span> <span class="o">=</span> <span class="s1">&#39;0.0.0.0&#39;</span>
<span class="c1"># Optional and needed only if using a proxy or similar. Change </span>
<span class="c1"># to the IP or address where the client can reach </span>
@ -244,19 +245,19 @@ change the outgoing port unless the default internal port is clashing with some
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.</p>
</div>
<div class="section" id="other-ports">
</section>
<section id="other-ports">
<h3>Other ports<a class="headerlink" href="#other-ports" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Optional public facing. Only allows SSL connections (off by default).</span>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Optional public facing. Only allows SSL connections (off by default).</span>
<span class="n">SSL_PORTS</span> <span class="o">=</span> <span class="p">[</span><span class="mi">4003</span><span class="p">]</span>
<span class="n">SSL_INTERFACES</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;0.0.0.0&#39;</span><span class="p">]</span>
<span class="c1"># Optional public facing. Only if you allow SSH connections (off by default).</span>
@ -271,16 +272,16 @@ based of the client instead, which tends to be slower.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">AMP_PORT</span></code> is required to work, since this is the internal port linking Evennia’s
<a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc">Server and Portal</span></a> components together. The other ports are encrypted ports that may be
useful for custom protocols but are otherwise not used.</p>
</div>
<div class="section" id="lockdown-mode">
</section>
<section id="lockdown-mode">
<h3>Lockdown mode<a class="headerlink" href="#lockdown-mode" title="Permalink to this headline"></a></h3>
<p>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
<code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code> and add <code class="docutils literal notranslate"><span class="pre">LOCKDOWN_MODE</span> <span class="pre">=</span> <span class="pre">True</span></code> to your settings file. When you start the server
again, your game will only be accessible from localhost.</p>
</div>
<div class="section" id="registering-with-the-evennia-game-directory">
</section>
<section id="registering-with-the-evennia-game-directory">
<h3>Registering with the Evennia game directory<a class="headerlink" href="#registering-with-the-evennia-game-directory" title="Permalink to this headline"></a></h3>
<p>Once your game is online you should make sure to register it with the <a class="reference external" href="http://games.evennia.com/">Evennia Game
Index</a>. Registering with the index will help people find your server,
@ -292,9 +293,9 @@ as <em>Not yet public</em> and just be a teaser. If so, pick <em>pre-alpha</em>
</pre></div>
</div>
<p>and follow the instructions. See the <a class="reference internal" href="Evennia-Game-Index.html"><span class="doc">Game index page</span></a> for more details.</p>
</div>
</div>
<div class="section" id="ssl">
</section>
</section>
<section id="ssl">
<h2>SSL<a class="headerlink" href="#ssl" title="Permalink to this headline"></a></h2>
<p>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
@ -311,7 +312,7 @@ that issues them for free with assisted setup to make the entire process less pa
<span class="n">WEBSOCKET_CLIENT_URL</span> <span class="o">=</span> <span class="s2">&quot;wss://fqdn:4002&quot;</span>
</pre></div>
</div>
<div class="section" id="let-s-encrypt">
<section id="let-s-encrypt">
<h3>Let’s Encrypt<a class="headerlink" href="#let-s-encrypt" title="Permalink to this headline"></a></h3>
<p><a class="reference external" href="https://letsencrypt.org">Let’s Encrypt</a> 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
@ -332,18 +333,18 @@ Domain Validation (DV)). This can be done either with configuring a certain path
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.</p>
</div>
</div>
<div class="section" id="relevant-ssl-proxy-setup-information">
</section>
</section>
<section id="relevant-ssl-proxy-setup-information">
<h2>Relevant SSL Proxy Setup Information<a class="headerlink" href="#relevant-ssl-proxy-setup-information" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Apache-Config.html"><span class="doc">Apache webserver configuration</span></a> (optional)</p></li>
<li><p><a class="reference internal" href="HAProxy-Config.html"><span class="doc">HAProxy Config</span></a></p></li>
</ul>
</div>
<div class="section" id="hosting-locally-or-remotely">
</section>
<section id="hosting-locally-or-remotely">
<h2>Hosting locally or remotely?<a class="headerlink" href="#hosting-locally-or-remotely" title="Permalink to this headline"></a></h2>
<div class="section" id="using-your-own-computer-as-a-server">
<section id="using-your-own-computer-as-a-server">
<h3>Using your own computer as a server<a class="headerlink" href="#using-your-own-computer-as-a-server" title="Permalink to this headline"></a></h3>
<p>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
@ -371,7 +372,7 @@ network, goes against your ISP’s terms of service (many ISPs insist on upselli
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.</p></li>
</ul>
<div class="section" id="setting-up-your-own-machine-as-a-server">
<section id="setting-up-your-own-machine-as-a-server">
<h4>Setting up your own machine as a server<a class="headerlink" href="#setting-up-your-own-machine-as-a-server" title="Permalink to this headline"></a></h4>
<p><a class="reference external" href="Setup/Online-Setup.html#connecting-from-the-outside">The first section</a> of this page describes how to do this
and allow users to connect to the IP address of your machine/router.</p>
@ -406,9 +407,9 @@ unique “hash”. Copy this string.</p></li>
from FreeDNS. The <code class="docutils literal notranslate"><span class="pre">&amp;</span></code> means we run in the background (might not be valid in other operating
systems). <code class="docutils literal notranslate"><span class="pre">inadyn</span></code> will henceforth check for changes every 60 seconds. You should put the <code class="docutils literal notranslate"><span class="pre">inadyn</span></code>
command string in a startup script somewhere so it kicks into gear whenever your computer starts.</p>
</div>
</div>
<div class="section" id="remote-hosting">
</section>
</section>
<section id="remote-hosting">
<h3>Remote hosting<a class="headerlink" href="#remote-hosting" title="Permalink to this headline"></a></h3>
<p>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
@ -445,7 +446,7 @@ least 100MB RAM and likely much more for a large production game.</p></li>
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).</p></li>
</ul>
<div class="section" id="installing-evennia-on-a-remote-server">
<section id="installing-evennia-on-a-remote-server">
<h4>Installing Evennia on a remote server<a class="headerlink" href="#installing-evennia-on-a-remote-server" title="Permalink to this headline"></a></h4>
<p>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.
@ -459,9 +460,9 @@ needed.</p>
from <a class="reference external" href="https://pypi.python.org/pypi/virtualenv">the virtualenv pypi</a>. Using <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> you can
install everything without actually needing to have further <code class="docutils literal notranslate"><span class="pre">root</span></code> access. Ports might be an issue,
so make sure you know which ports are available to use and reconfigure Evennia accordingly.</p>
</div>
</div>
<div class="section" id="hosting-options">
</section>
</section>
<section id="hosting-options">
<h3>Hosting options<a class="headerlink" href="#hosting-options" title="Permalink to this headline"></a></h3>
<p>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
@ -501,9 +502,9 @@ servers with this option as they don’t have a lot of support.
<a class="reference external" href="https://amazonlightsail.com">9</a>
<a class="reference external" href="https://prgmr.com/">10</a>
<a class="reference external" href="https://www.linode.com/">11</a></p>
</div>
</div>
<div class="section" id="cloud9">
</section>
</section>
<section id="cloud9">
<h2>Cloud9<a class="headerlink" href="#cloud9" title="Permalink to this headline"></a></h2>
<p>If you are interested in running Evennia in the online dev environment <a class="reference external" href="https://c9.io/">Cloud9</a>, you
can spin it up through their normal online setup using the Evennia Linux install instructions. The
@ -514,8 +515,8 @@ else as normal.</p>
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/</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

15
docs/1.0-dev/Setup/RSS.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>RSS &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="rss">
<section id="rss">
<h1>RSS<a class="headerlink" href="#rss" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="http://en.wikipedia.org/wiki/RSS">RSS</a> 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
@ -48,7 +49,7 @@ example the MUD might use a separate website to host its forums. Through RSS, th
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
<a class="reference external" href="http://code.google.com/feeds/p/evennia/updates/basic">here</a>.</p>
<div class="section" id="configuring-rss">
<section id="configuring-rss">
<h2>Configuring RSS<a class="headerlink" href="#configuring-rss" title="Permalink to this headline"></a></h2>
<p>To use RSS, you first need to install the <a class="reference external" href="http://code.google.com/p/feedparser/">feedparser</a> python
module.</p>
@ -60,7 +61,7 @@ module.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@rss2chan</span> <span class="o">&lt;</span><span class="n">evennia_channel</span><span class="o">&gt;</span> <span class="o">=</span> <span class="o">&lt;</span><span class="n">rss_url</span><span class="o">&gt;</span>
</pre></div>
</div>
<div class="section" id="setting-up-rss-step-by-step">
<section id="setting-up-rss-step-by-step">
<h3>Setting up RSS, step by step<a class="headerlink" href="#setting-up-rss-step-by-step" title="Permalink to this headline"></a></h3>
<p>You can connect RSS to any Evennia channel, but for testing, let’s set up a new channel “rss”.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> @ccreate rss = RSS feeds are echoed to this channel!
@ -80,9 +81,9 @@ switch:</p>
</div>
<p>You can connect any number of RSS feeds to a channel this way. You could also connect them to the
same channels as <a class="reference internal" href="IRC.html"><span class="doc">IRC</span></a> to have the feed echo to external chat channels as well.</p>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>

63
docs/1.0-dev/Setup/Running-Evennia-in-Docker.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Running Evennia in Docker &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,11 +38,11 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="running-evennia-in-docker">
<section id="running-evennia-in-docker">
<h1>Running Evennia in Docker<a class="headerlink" href="#running-evennia-in-docker" title="Permalink to this headline"></a></h1>
<p>Evennia has an <a class="reference external" href="https://hub.docker.com/r/evennia/evennia/">official docker image</a> which makes
running an Evennia-based game in a Docker container easy.</p>
<div class="section" id="install-evennia-through-docker">
<section id="install-evennia-through-docker">
<h2>Install Evennia through docker<a class="headerlink" href="#install-evennia-through-docker" title="Permalink to this headline"></a></h2>
<p>First, install the <code class="docutils literal notranslate"><span class="pre">docker</span></code> program so you can run the Evennia container. You can get it freely from
<a class="reference external" href="https://www.docker.com/">docker.com</a>. Linux users can likely also get it through their normal
@ -62,7 +63,7 @@ in the future. This tracks the <code class="docutils literal notranslate"><span
<p>$UID:$GID evennia/evennia</p>
<p>Having run this (see next section for a description of what’s what), you will be at a prompt inside
the docker container:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span>evennia<span class="p">|</span>docker /usr/src/game $
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>evennia<span class="p">|</span>docker /usr/src/game $
</pre></div>
</td></tr></table></div>
<p>This is a normal shell prompt. We are in the <code class="docutils literal notranslate"><span class="pre">/usr/src/game</span></code> location inside the docker container.
@ -79,10 +80,10 @@ by <code class="docutils literal notranslate"><span class="pre">root</span></cod
On Linux/Mac you do this with <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">chown</span> <span class="pre">myname:myname</span> <span class="pre">-R</span> <span class="pre">mygame</span></code>, where you replace <code class="docutils literal notranslate"><span class="pre">myname</span></code> with
your username and <code class="docutils literal notranslate"><span class="pre">mygame</span></code> with whatever your game folder is named.</p>
</div></blockquote>
<div class="section" id="description-of-the-docker-run-command">
<section id="description-of-the-docker-run-command">
<h3>Description of the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span></code> command<a class="headerlink" href="#description-of-the-docker-run-command" title="Permalink to this headline"></a></h3>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2</pre></div></td><td class="code"><div class="highlight"><pre><span></span> docker run -it --rm -p <span class="m">4000</span>:4000 -p <span class="m">4001</span>:4001 -p <span class="m">4002</span>:4002 --rm -v <span class="nv">$PWD</span>:/usr/src/game --user
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> docker run -it --rm -p <span class="m">4000</span>:4000 -p <span class="m">4001</span>:4001 -p <span class="m">4002</span>:4002 --rm -v <span class="nv">$PWD</span>:/usr/src/game --user
<span class="nv">$UID</span>:<span class="nv">$GID</span> evennia/evennia
</pre></div>
</td></tr></table></div>
@ -112,9 +113,9 @@ group IDs instead of root’s IDs (root is the user running evennia inside the c
having stale <code class="docutils literal notranslate"><span class="pre">.pid</span></code> files in your filesystem between container reboots which you have to force
delete with <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">rm</span> <span class="pre">server/*.pid</span></code> before each boot.</p></li>
</ul>
</div>
</div>
<div class="section" id="running-your-game-as-a-docker-image">
</section>
</section>
<section id="running-your-game-as-a-docker-image">
<h2>Running your game as a docker image<a class="headerlink" href="#running-your-game-as-a-docker-image" title="Permalink to this headline"></a></h2>
<p>If you run the <code class="docutils literal notranslate"><span class="pre">docker</span></code> 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.</p>
@ -125,7 +126,7 @@ or updating your game as simple as building a new container image locally, pushi
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.</p>
<div class="section" id="start-evennia-and-run-through-docker">
<section id="start-evennia-and-run-through-docker">
<h3>Start Evennia and run through docker<a class="headerlink" href="#start-evennia-and-run-through-docker" title="Permalink to this headline"></a></h3>
<p>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
@ -139,8 +140,8 @@ run in the container. From your game dir, run for example this command:</p>
terminal will kill the server. Note that you <em>must</em> use a foreground command like <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span> <span class="pre">-l</span></code>
or <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">ipstart</span></code> to start the server - otherwise the foreground process will finish immediately
and the container go down.</p>
</div>
<div class="section" id="create-your-own-game-image">
</section>
<section id="create-your-own-game-image">
<h3>Create your own game image<a class="headerlink" href="#create-your-own-game-image" title="Permalink to this headline"></a></h3>
<p>These steps assume that you have created or otherwise obtained a game directory already. First, <code class="docutils literal notranslate"><span class="pre">cd</span></code>
to your game dir and create a new empty text file named <code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code>. Save the following two lines
@ -154,7 +155,7 @@ into it:</p>
<code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> image, but also makes sure to start evennia when it runs (so we don’t need to
enter it and run commands).</p>
<p>To build the image:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span> docker build -t mydhaccount/mygame .
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> docker build -t mydhaccount/mygame .
</pre></div>
</td></tr></table></div>
<p>(don’t forget the period at the end, it will use the <code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code> from the current location). Here
@ -163,8 +164,8 @@ build the image locally only (name the container whatever you like in that case,
<code class="docutils literal notranslate"><span class="pre">mygame</span></code>).</p>
<p>Docker images are stored centrally on your computer. You can see which ones you have available
locally with <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">images</span></code>. Once built, you have a couple of options to run your game.</p>
</div>
<div class="section" id="run-container-from-your-game-image-for-development">
</section>
<section id="run-container-from-your-game-image-for-development">
<h3>Run container from your game image for development<a class="headerlink" href="#run-container-from-your-game-image-for-development" title="Permalink to this headline"></a></h3>
<p>To run the container based on your game image locally for development, mount the local game
directory as before:</p>
@ -174,8 +175,8 @@ mydhaccount/mygame
</div>
<p>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.</p>
</div>
<div class="section" id="deploy-game-image-for-production">
</section>
<section id="deploy-game-image-for-production">
<h3>Deploy game image for production<a class="headerlink" href="#deploy-game-image-for-production" title="Permalink to this headline"></a></h3>
<p>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 <code class="docutils literal notranslate"><span class="pre">/usr/src/game/</span></code>). If you don’t mount your on-disk
@ -189,10 +190,10 @@ the image and started on the server! If your server environment forces you to us
you can just map the normal ports differently in the command above.</p>
<p>Above we added the <code class="docutils literal notranslate"><span class="pre">-d</span></code> option, which starts the container in <em>daemon</em> mode - you won’t see any
return in the console. You can see it running with <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">ps</span></code>:</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ docker ps
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>$ docker ps
CONTAINER ID IMAGE COMMAND CREATED ...
f6d4ca9b2b22 mygame <span class="s2">&quot;/bin/sh -c &#39;evenn...&quot;</span> About a minute ago ...
@ -220,9 +221,9 @@ f6d4ca9b2b22 mygame <span class="s2">&quot;/bin/sh -c &#39;evenn...&quo
</div>
<p>Stop the container. To get it up again you need to use <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span></code>, specifying ports etc. A new
container will get a new container id to reference.</p>
</div>
</div>
<div class="section" id="how-it-works">
</section>
</section>
<section id="how-it-works">
<h2>How it Works<a class="headerlink" href="#how-it-works" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> docker image holds the evennia library and all of its dependencies. It also
has an <code class="docutils literal notranslate"><span class="pre">ONBUILD</span></code> directive which is triggered during builds of images derived from it. This
@ -234,7 +235,7 @@ your image on Docker Hub and would like to provide contact info.</p>
Reference</a>.</p>
<p>For more information on volumes and Docker containers, see the Docker site’s <a class="reference external" href="https://docs.docker.com/engine/tutorials/dockervolumes/">Manage data in
containers</a> page.</p>
<div class="section" id="what-if-i-don-t-want-latest">
<section id="what-if-i-don-t-want-latest">
<h3>What if I Don’t Want “LATEST”?<a class="headerlink" href="#what-if-i-don-t-want-latest" title="Permalink to this headline"></a></h3>
<p>A new <code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> image is built automatically whenever there is a new commit to the <code class="docutils literal notranslate"><span class="pre">master</span></code>
branch of Evennia. It is possible to create your own custom evennia base docker image based on any
@ -274,9 +275,9 @@ working directory to be your game directory and run</p></li>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docker</span> <span class="n">build</span> <span class="o">-</span><span class="n">t</span> <span class="n">mydhaccountt</span><span class="o">/</span><span class="n">mygame</span> <span class="o">.</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="additional-creature-comforts">
</section>
</section>
<section id="additional-creature-comforts">
<h2>Additional Creature Comforts<a class="headerlink" href="#additional-creature-comforts" title="Permalink to this headline"></a></h2>
<p>The Docker ecosystem includes a tool called <code class="docutils literal notranslate"><span class="pre">docker-compose</span></code>, which can orchestrate complex multi-
container applications, or in our case, store the default port and terminal parameters that we want
@ -310,8 +311,8 @@ hardcode your user and group id. In a terminal run <code class="docutils literal
<code class="docutils literal notranslate"><span class="pre">1000:1000</span></code> you can add to <code class="docutils literal notranslate"><span class="pre">docker-compose.yml</span></code> a line <code class="docutils literal notranslate"><span class="pre">user:</span> <span class="pre">1000:1000</span></code> just below the <code class="docutils literal notranslate"><span class="pre">image:</span> <span class="pre">...</span></code>
line.</p>
</div></blockquote>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

37
docs/1.0-dev/Setup/Security.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Security &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="security">
<section id="security">
<h1>Security<a class="headerlink" href="#security" title="Permalink to this headline"></a></h1>
<p>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
@ -52,7 +53,7 @@ blacklisted by ISPs. It can be a difficult legal or political battle to undo thi
fact.</p>
<p>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.</p>
<div class="section" id="know-your-logs">
<section id="know-your-logs">
<h2>Know your logs<a class="headerlink" href="#know-your-logs" title="Permalink to this headline"></a></h2>
<p>In case of emergency, check your logs! By default they are located in the <code class="docutils literal notranslate"><span class="pre">server/logs/</span></code> folder.
Here are some of the more important ones and why you should care:</p>
@ -69,8 +70,8 @@ objects, and more. If your game fails to start or crashes and you can’t tell w
place you should look for answers. Security-related events are prefixed with an <code class="docutils literal notranslate"><span class="pre">[SS]</span></code> so when
there’s a problem you might want to pay special attention to those.</p></li>
</ul>
</div>
<div class="section" id="disable-development-debugging-options">
</section>
<section id="disable-development-debugging-options">
<h2>Disable development/debugging options<a class="headerlink" href="#disable-development-debugging-options" title="Permalink to this headline"></a></h2>
<p>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
@ -86,9 +87,9 @@ abuse to compromise your environment.</p>
</div>
<p>as-is.
# Note the leading period– it is not a typo!
ALLOWED_HOSTS = [‘.example.com’]</p>
</div>
<div class="section" id="handle-user-uploaded-images-with-care">
ALLOWED_HOSTS = [’.example.com’]</p>
</section>
<section id="handle-user-uploaded-images-with-care">
<h2>Handle user-uploaded images with care<a class="headerlink" href="#handle-user-uploaded-images-with-care" title="Permalink to this headline"></a></h2>
<p>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
@ -109,8 +110,8 @@ resources in bulk).</p></li>
bothered with additional infrastructure, then simply reprocess user images upon receipt using an
image library. Convert them to a different format, for example. <em>Destroy the originals!</em></p></li>
</ul>
</div>
<div class="section" id="disable-the-web-interface">
</section>
<section id="disable-the-web-interface">
<h2>Disable the web interface<a class="headerlink" href="#disable-the-web-interface" title="Permalink to this headline"></a></h2>
<p>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
@ -125,8 +126,8 @@ either/both to minimize your attack surface.</p>
<span class="n">WEBSERVER_ENABLED</span> <span class="o">=</span> <span class="kc">False</span>
</pre></div>
</div>
</div>
<div class="section" id="change-your-ssh-port">
</section>
<section id="change-your-ssh-port">
<h2>Change your ssh port<a class="headerlink" href="#change-your-ssh-port" title="Permalink to this headline"></a></h2>
<p>Automated attacks will often target port 22 seeing as how it’s the standard port for SSH traffic.
Also,
@ -144,8 +145,8 @@ allows through.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">service</span> <span class="n">ssh</span> <span class="n">restart</span>
</pre></div>
</div>
</div>
<div class="section" id="set-up-a-firewall">
</section>
<section id="set-up-a-firewall">
<h2>Set up a firewall<a class="headerlink" href="#set-up-a-firewall" title="Permalink to this headline"></a></h2>
<p>Ubuntu users can make use of the simple ufw utility. Anybody else can use iptables.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ufw (if not already)</span>
@ -171,8 +172,8 @@ firewall.</p>
</div>
<p>Now the only ports open will be your administrative ssh port (whichever you chose), and Evennia on
4000-4001.</p>
</div>
<div class="section" id="use-an-external-webserver">
</section>
<section id="use-an-external-webserver">
<h2>Use an external webserver<a class="headerlink" href="#use-an-external-webserver" title="Permalink to this headline"></a></h2>
<p>Though not officially supported, there are some benefits to <a class="reference internal" href="Apache-Config.html"><span class="doc">deploying a webserver</span></a>
to handle/proxy traffic to your Evennia instance.</p>
@ -190,8 +191,8 @@ nuisances and crowds before they even get in the door.</p>
automated solutions for installing and configuring TLS (via <a class="reference external" href="https://en.wikipedia.org/wiki/Let%27s_Encrypt">Certbot/Let’s
Encrypt</a>) to secure your website against hotspot and
ISP snooping.</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

7
docs/1.0-dev/Setup/Settings-File.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>The Evennia Default Settings file &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,10 +38,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-evennia-default-settings-file">
<section id="the-evennia-default-settings-file">
<h1>The Evennia Default Settings file<a class="headerlink" href="#the-evennia-default-settings-file" title="Permalink to this headline"></a></h1>
<p>TODO</p>
</div>
</section>
<div class="clearer"></div>

23
docs/1.0-dev/Setup/Setup-Overview.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Server Setup and Life &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -45,10 +46,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="server-setup-and-life">
<section id="server-setup-and-life">
<h1>Server Setup and Life<a class="headerlink" href="#server-setup-and-life" title="Permalink to this headline"></a></h1>
<p>This documentation covers how to setup and maintain the server, from first install to opening your game to the public.</p>
<div class="section" id="installation-running">
<section id="installation-running">
<h2>Installation &amp; running<a class="headerlink" href="#installation-running" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Setup-Quickstart.html"><span class="doc">Installation &amp; Setup quick-start</span></a> - one page to quickly get you going</p></li>
@ -57,14 +58,14 @@
<li><p><a class="reference internal" href="Installing-on-Android.html"><span class="doc">Installing Evennia on Android</span></a> - for those craving a mobile life</p></li>
<li><p><a class="reference internal" href="Start-Stop-Reload.html"><span class="doc">Controlling the server</span></a> - an extended view on how to start/stop/update the server</p></li>
</ul>
</div>
<div class="section" id="installing-custom-game-dirs">
</section>
<section id="installing-custom-game-dirs">
<h2>Installing custom game dirs<a class="headerlink" href="#installing-custom-game-dirs" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="../Contribs/Arxcode-installing-help.html"><span class="doc">Installing Arxcode</span></a> - a custom gamedir based on the popular Evennia game <a class="reference external" href="https://play.arxgame.org/">Arx</a></p></li>
</ul>
</div>
<div class="section" id="configuring">
</section>
<section id="configuring">
<h2>Configuring<a class="headerlink" href="#configuring" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Settings-File.html"><span class="doc">The settings file</span></a> - how and where to change the main settings of the server</p></li>
@ -75,8 +76,8 @@
<li><p><a class="reference internal" href="RSS.html"><span class="doc">Messages to RSS</span></a> - have your game notify people through RSS</p></li>
<li><p><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html"><span class="doc">Messages to Twitter</span></a> - have Evennia send messages to <a class="reference external" href="https://twitter.com/">Twitter</a> (requires some coding)</p></li>
</ul>
</div>
<div class="section" id="going-public">
</section>
<section id="going-public">
<h2>Going public<a class="headerlink" href="#going-public" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Security.html"><span class="doc">Notes about security</span></a> - some things to think about to stay safe(r)</p>
@ -88,8 +89,8 @@
<li><p><a class="reference internal" href="Online-Setup.html"><span class="doc">Taking your server online</span></a> - decide on where to host and configure your game for production</p></li>
<li><p><a class="reference internal" href="Client-Support-Grid.html"><span class="doc">Client support grid</span></a> - clients known to work (or not) with Evennia</p></li>
</ul>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

50
docs/1.0-dev/Setup/Setup-Quickstart.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Setup quickstart &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -45,14 +46,14 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="setup-quickstart">
<section id="setup-quickstart">
<h1>Setup quickstart<a class="headerlink" href="#setup-quickstart" title="Permalink to this headline"></a></h1>
<p>The Evennia server is installed, run and maintained from the terminal (console/CMD on Windows). Starting the
server doesn’t make anything visible online. Once you download everything you can in fact develop your game
in complete isolation if you want, without needing any access to the internet.</p>
<div class="section" id="installation">
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
<p>Evennia requires Python3.7+. As with most Python packages, using a
<p>Evennia supports Python 3.7 to 3.9. As with most Python packages, using a
<a class="reference external" href="Glossary.html#virtualenv">virtualenv</a> is recommended in order to keep your
installation independent from the system libraries. It’s <em>not</em> recommended
to install Evennia as superuser.</p>
@ -64,12 +65,13 @@ to install Evennia as superuser.</p>
</pre></div>
</div>
<p>Make sure the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command works. Use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">-h</span></code> for usage help (or read on).</p>
<p>If you are having trouble, want to install in some other way (like with Docker) or want to contribute to
Evennia itself, check out the <a class="reference internal" href="Extended-Installation.html"><span class="doc">Extended Installation instructions</span></a>.
It also has a <a class="reference external" href="Setup/Extended-Installation.html#Troubleshooting">troubleshooting section</a> for different operating
<p>If you are having trouble, want to install in some other way (like with Docker)
or want to contribute to Evennia itself, check out the <a class="reference internal" href="Extended-Installation.html"><span class="doc">Extended Installation
instructions</span></a>. It also has a <a class="reference external" href="Setup/Extended-Installation.html#Troubleshooting">troubleshooting
section</a> for different operating
systems.</p>
</div>
<div class="section" id="initialize-a-new-game">
</section>
<section id="initialize-a-new-game">
<h2>Initialize a new game<a class="headerlink" href="#initialize-a-new-game" title="Permalink to this headline"></a></h2>
<p>Use <code class="docutils literal notranslate"><span class="pre">cd</span></code> 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 <code class="docutils literal notranslate"><span class="pre">mygame</span></code>, but you should of course
@ -79,8 +81,8 @@ name your game whatever you like:</p>
</div>
<p>This will create a new folder <code class="docutils literal notranslate"><span class="pre">mygame</span></code> (or whatever you chose) in your current location. This
contains empty templates and all the default settings needed to start the server.</p>
</div>
<div class="section" id="start-the-new-game">
</section>
<section id="start-the-new-game">
<h2>Start the new game<a class="headerlink" href="#start-the-new-game" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">cd</span></code> into your game folder (<code class="docutils literal notranslate"><span class="pre">mygame</span></code> in our case). Next, run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">migrate</span>
@ -88,7 +90,7 @@ contains empty templates and all the default settings needed to start the server
</div>
<p>This will create the default database (Sqlite3). The database file ends up as <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. If you
ever want to start from a fresh database, just delete this file and re-run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> again.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">start</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">start</span>
</pre></div>
</div>
<p>Set your user-name and password when prompted. This will be the “god user” or “superuser” in-game. The email is optional.</p>
@ -97,43 +99,43 @@ a web browser at <a class="reference external" href="http://localhost:4001">http
<blockquote>
<div><p>If <code class="docutils literal notranslate"><span class="pre">localhost</span></code> doesn’t work on your computer, use <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>, which is the same thing.</p>
</div></blockquote>
</div>
<div class="section" id="see-server-logs">
</section>
<section id="see-server-logs">
<h2>See server logs<a class="headerlink" href="#see-server-logs" title="Permalink to this headline"></a></h2>
<p>This will echol the server logs to the terminal as they come in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">log</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">-</span><span class="n">l</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">-</span><span class="n">l</span>
</pre></div>
</div>
<p>You can also start logging immediately when running <code class="docutils literal notranslate"><span class="pre">evennia</span></code> commands, such as</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">start</span> <span class="o">-</span><span class="n">l</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">start</span> <span class="o">-</span><span class="n">l</span>
</pre></div>
</div>
<p>To exit the log view, enter <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> (<code class="docutils literal notranslate"><span class="pre">Cmd-C</span></code> for Mac). This will not affect the server.</p>
</div>
<div class="section" id="restarting-and-stopping">
</section>
<section id="restarting-and-stopping">
<h2>Restarting and stopping<a class="headerlink" href="#restarting-and-stopping" title="Permalink to this headline"></a></h2>
<p>You can restart the server without disconnecting any connected players:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">restart</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">restart</span>
</pre></div>
</div>
<p>To do a full stop and restart (will disconnect everyone):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">reboot</span>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">reboot</span>
</pre></div>
</div>
<p>Full stop of the server (will need to use <code class="docutils literal notranslate"><span class="pre">start</span></code> to activate it again):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">stop</span>
</pre></div>
</div>
</div>
<div class="section" id="the-next-step">
</section>
<section id="the-next-step">
<h2>The Next step<a class="headerlink" href="#the-next-step" title="Permalink to this headline"></a></h2>
<p>Why not head into the <a class="reference internal" href="../Howto/Starting/Part1/Starting-Part1.html"><span class="doc">Starting Tutorial</span></a> to learn how to start making your new game!</p>
</div>
</div>
</section>
</section>
<div class="clearer"></div>

57
docs/1.0-dev/Setup/Start-Stop-Reload.html
View file

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Start Stop Reload &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -37,7 +38,7 @@
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="start-stop-reload">
<section id="start-stop-reload">
<h1>Start Stop Reload<a class="headerlink" href="#start-stop-reload" title="Permalink to this headline"></a></h1>
<p>You control Evennia from your game folder (we refer to it as <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> here), using the <code class="docutils literal notranslate"><span class="pre">evennia</span></code>
program. If the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program is not available on the command line you must first install
@ -55,7 +56,7 @@ available, make sure your <a class="reference external" href="Glossary.html#virt
</pre></div>
</div>
<p>to give you a menu with options.</p>
<div class="section" id="starting-evennia">
<section id="starting-evennia">
<h2>Starting Evennia<a class="headerlink" href="#starting-evennia" title="Permalink to this headline"></a></h2>
<p>Evennia consists of two components, the Evennia <a class="reference internal" href="../Components/Portal-And-Server.html"><span class="doc">Server and Portal</span></a>. Briefly,
the <em>Server</em> is what is running the mud. It handles all game-specific things but doesn’t care
@ -79,8 +80,8 @@ those logs directly in your terminal by attaching <code class="docutils literal
<blockquote>
<div><p>To stop viewing the log files, press <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code>.</p>
</div></blockquote>
</div>
<div class="section" id="foreground-mode">
</section>
<section id="foreground-mode">
<h2>Foreground mode<a class="headerlink" href="#foreground-mode" title="Permalink to this headline"></a></h2>
<p>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 <em>interactive</em> mode. This means they will log
@ -96,8 +97,8 @@ kill the process (not just the log-file view) with <code class="docutils literal
</div>
<p>will start the <em>Portal</em> in interactive mode. This is usually only necessary if you want to run
Evennia under the control of some other type of process.</p>
</div>
<div class="section" id="reloading">
</section>
<section id="reloading">
<h2>Reloading<a class="headerlink" href="#reloading" title="Permalink to this headline"></a></h2>
<p>The act of <em>reloading</em> 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
@ -113,8 +114,8 @@ can save eventual temporary properties you want.</p>
</div>
<p>Sometimes reloading from “the outside” is necessary in case you have added some sort of bug that
blocks in-game input.</p>
</div>
<div class="section" id="resetting">
</section>
<section id="resetting">
<h2>Resetting<a class="headerlink" href="#resetting" title="Permalink to this headline"></a></h2>
<p><em>Resetting</em> 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
@ -125,8 +126,8 @@ hooks. It can be a good way to clean unsafe scripts during development, for exam
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">reset</span>
</pre></div>
</div>
</div>
<div class="section" id="rebooting">
</section>
<section id="rebooting">
<h2>Rebooting<a class="headerlink" href="#rebooting" title="Permalink to this headline"></a></h2>
<p>This will shut down <em>both</em> Server and Portal, which means all connected players will lose their
connection. It can only be initiated from the terminal:</p>
@ -138,8 +139,8 @@ connection. It can only be initiated from the terminal:</p>
<span class="n">evennia</span> <span class="n">start</span>
</pre></div>
</div>
</div>
<div class="section" id="shutting-down">
</section>
<section id="shutting-down">
<h2>Shutting down<a class="headerlink" href="#shutting-down" title="Permalink to this headline"></a></h2>
<p>A full shutdown closes Evennia completely, both Server and Portal. All accounts will be booted and
systems saved and turned off cleanly.</p>
@ -150,8 +151,8 @@ systems saved and turned off cleanly.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">Ctrl+C</span></code> while the server
runs in interactive mode.</p>
</div>
<div class="section" id="status-and-info">
</section>
<section id="status-and-info">
<h2>Status and info<a class="headerlink" href="#status-and-info" title="Permalink to this headline"></a></h2>
<p>To check basic Evennia settings, such as which ports and services are active, this will repeat the
initial return given when starting the server:</p>
@ -163,8 +164,8 @@ initial return given when starting the server:</p>
</pre></div>
</div>
<p>This can be useful for automating checks to make sure the game is running and is responding.</p>
</div>
<div class="section" id="killing-linux-mac-only">
</section>
<section id="killing-linux-mac-only">
<h2>Killing (Linux/Mac only)<a class="headerlink" href="#killing-linux-mac-only" title="Permalink to this headline"></a></h2>
<p>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:</p>
@ -176,22 +177,22 @@ you can send them kill-signals to force them to shut down. To kill only the Serv
</pre></div>
</div>
<p>Note that this functionality is not supported on Windows.</p>
</div>
<div class="section" id="django-options">
</section>
<section id="django-options">
<h2>Django options<a class="headerlink" href="#django-options" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program will also pass-through options used by the <code class="docutils literal notranslate"><span class="pre">django-admin</span></code>. These operate on
the database in various ways.</p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span> evennia migrate <span class="c1"># migrate the database</span>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> evennia migrate <span class="c1"># migrate the database</span>
evennia shell <span class="c1"># launch an interactive, django-aware python shell</span>
evennia dbshell <span class="c1"># launch database shell</span>
</pre></div>
</td></tr></table></div>
<p>For (many) more options, see <a class="reference external" href="https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage">the django-admin
docs</a>.</p>
</div>
<div class="section" id="advanced-handling-of-evennia-processes">
</section>
<section id="advanced-handling-of-evennia-processes">
<h2>Advanced handling of Evennia processes<a class="headerlink" href="#advanced-handling-of-evennia-processes" title="Permalink to this headline"></a></h2>
<p>If you should need to manually manage Evennia’s processors (or view them in a task manager program
such as Linux’ <code class="docutils literal notranslate"><span class="pre">top</span></code> or the more advanced <code class="docutils literal notranslate"><span class="pre">htop</span></code>), you will find the following processes to be
@ -203,7 +204,7 @@ game. The other processes (with the same name but different process id) handle
internal web server threads. You can look at <code class="docutils literal notranslate"><span class="pre">mygame/server/server.pid</span></code> to determine which is the
main process.</p></li>
</ul>
<div class="section" id="syntax-errors-during-live-development">
<section id="syntax-errors-during-live-development">
<h3>Syntax errors during live development<a class="headerlink" href="#syntax-errors-during-live-development" title="Permalink to this headline"></a></h3>
<p>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
@ -222,9 +223,9 @@ wrong.</p>
</div>
<p>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.</p>
</div>
</div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>