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

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2020-07-14 00:21:00 +02:00
parent a551188691
commit 781788f2e5
2063 changed files with 215958 additions and 250783 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -0,0 +1,295 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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
works out of the box without any extra configuration and also runs in-process making sure to avoid
caching race conditions. The browser web client will most likely not work (at least not without
tweaking) on a third-party web server.</p>
<p>One reason for wanting to use an external webserver like Apache would be to act as a <em>proxy</em> in
front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work
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">
<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">
<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
repositories for Fedora and RHEL:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dnf install httpd mod_wsgi
or
$ yum install httpd mod_wsgi
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> are available in the standard package
repositories for Ubuntu and Debian:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ apt-get update
$ apt-get install apache2 libapache2-mod-wsgi
</pre></div>
</div>
</li>
</ul>
</div>
<div class="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">
<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>
<li><p><em>Fedora/RHEL/Ubuntu</em></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ systemctl restart httpd
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ systemctl restart apache2
</pre></div>
</div>
</li>
</ul>
</div>
<div class="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">
<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
<code class="docutils literal notranslate"><span class="pre">evennia/game/web/utils/apache_wsgi.conf</span></code>. When <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> sees that the file modification time has
changed, it will force a code reload. Any modifications to the code will not be propagated to the
live instance of your site until reloaded.</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">
<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,
some Linux distributions may default to very restrictive access permissions on a user’s <code class="docutils literal notranslate"><span class="pre">/home</span></code>
directory.</p>
<p>One user commented that they had to add the following to their Apache config to get things to work.
Not confirmed, but worth trying if there are trouble.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Directory</span> <span class="s2">&quot;/home/&lt;yourname&gt;/evennia/game/web&quot;</span><span class="o">&gt;</span>
<span class="n">Options</span> <span class="o">+</span><span class="n">ExecCGI</span>
<span class="n">Allow</span> <span class="kn">from</span> <span class="nn">all</span>
<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">
<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">
<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
repositories for Fedora and RHEL:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dnf install httpd mod_ssl
or
$ yum install httpd mod_ssl
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_sslj</span></code>kl are installed together in the <code class="docutils literal notranslate"><span class="pre">apache2</span></code>
package and available in the
standard package repositories for Ubuntu and Debian. <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> needs to be enabled after
installation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ apt-get update
$ apt-get install apache2
$ a2enmod ssl
</pre></div>
</div>
</li>
</ul>
</div>
<div class="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">
<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
ServerName mud.example.com
Redirect / https://mud.example.com
&lt;/VirtualHost&gt;
&lt;VirtualHost *:443&gt;
ServerName mud.example.com
SSLEngine On
# Location of certificate and key
SSLCertificateFile /etc/pki/tls/certs/mud.example.com.crt
SSLCertificateKeyFile /etc/pki/tls/private/mud.example.com.key
# Use a tool https://www.ssllabs.com/ssltest/ to scan your set after setting up.
SSLProtocol TLSv1.2
SSLCipherSuite HIGH:!eNULL:!NULL:!aNULL
# Proxy all websocket traffic to port 4002 in Evennia
ProxyPass /ws ws://127.0.0.1:4002/
ProxyPassReverse /ws ws://127.0.0.1:4002/
# Proxy all HTTP traffic to port 4001 in Evennia
ProxyPass / http://127.0.0.1:4001/
ProxyPassReverse / http://127.0.0.1:4001/
# Configure separate logging for this Evennia proxy
ErrorLog logs/evennia_error.log
CustomLog logs/evennia_access.log combined
&lt;/VirtualHost&gt;
</pre></div>
</div>
</div>
<div class="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>
<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://external.example.com/ws&quot;</span>
</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
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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Apache Config</a><ul>
<li><a class="reference internal" href="#mod-wsgi-setup"><code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> Setup</a><ul>
<li><a class="reference internal" href="#install-mod-wsgi">Install <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code></a></li>
<li><a class="reference internal" href="#copy-and-modify-the-vhost">Copy and modify the VHOST</a></li>
<li><a class="reference internal" href="#restart-reload-apache">Restart/Reload Apache</a></li>
<li><a class="reference internal" href="#enjoy">Enjoy</a></li>
<li><a class="reference internal" href="#a-note-on-code-reloading">A note on code reloading</a></li>
<li><a class="reference internal" href="#further-notes-and-hints">Further notes and hints:</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mod-proxy-and-mod-ssl-setup"><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><ul>
<li><a class="reference internal" href="#install-mod-ssl">Install <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code></a></li>
<li><a class="reference internal" href="#tls-proxy-websocket-configuration">TLS proxy+websocket configuration</a><ul>
<li><a class="reference internal" href="#apache-http-server-configuration">Apache HTTP Server Configuration</a></li>
<li><a class="reference internal" href="#evennia-secure-websocket-configuration">Evennia secure websocket configuration</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Apache-Config.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Apache-Config.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,387 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Choosing An SQL Server</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<li><p>SQLite3 (default)</p></li>
<li><p>PostgreSQL</p></li>
<li><p>MySQL / MariaDB</p></li>
</ul>
<p>Since Evennia uses <a class="reference external" href="http://djangoproject.com">Django</a>, most of our notes are based off of what we
know from the community and their documentation. While the information below may be useful, you can
always find the most up-to-date and “correct” information at Django’s <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">
<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
database in a single file (<code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>). This means it’s very easy to reset this
database - just delete (or move) that <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code> file and run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> again! No server
process is needed and the administrative overhead and resource consumption is tiny. It is also very
fast since it’s run in-memory. For the vast majority of Evennia installs it will probably be all
that’s ever needed.</p>
<p>SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:</p>
<ul class="simple">
<li><p>SQLite <a class="reference external" href="https://www.sqlite.org/faq.html#q9">ignores length constraints by design</a>; it is possible
to store very large strings and numbers in fields that technically should not accept them. This is
not something you will notice; your game will read and write them and function normally, but this
<em>can</em> create some data migration problems requiring careful thought if you do need to change
databases later.</p></li>
<li><p>SQLite can scale well to storage of millions of objects, but if you end up with a thundering herd
of users trying to access your MUD and web site at the same time, or you find yourself writing long-
running functions to update large numbers of objects on a live game, either will yield errors and
interference. SQLite does not work reliably with multiple concurrent threads or processes accessing
its records. This has to do with file-locking clashes of the database file. So for a production
server making heavy use of process- or thread pools (or when using a third-party webserver like
Apache), a proper database is a more appropriate choice.</p></li>
</ul>
<div class="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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">migrate</span>
</pre></div>
</div>
<p>without changing any database options. An optional requirement is the <code class="docutils literal notranslate"><span class="pre">sqlite3</span></code> client program -
this is required if you want to inspect the database data manually. A shortcut for using it with the
evennia database is <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code>. Linux users should look for the <code class="docutils literal notranslate"><span class="pre">sqlite3</span></code> package for their
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
<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">
<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">
<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
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
</pre></div>
</td></tr></table></div>
<blockquote>
<div><p>:warning: <strong>Warning:</strong> With the <code class="docutils literal notranslate"><span class="pre">--password</span></code> argument, Postgres should prompt you for a password.
If it won’t, replace that with <code class="docutils literal notranslate"><span class="pre">-p</span> <span class="pre">yourpassword</span></code> instead. Do not use the <code class="docutils literal notranslate"><span class="pre">-p</span></code> argument unless you
have to since the resulting command, and your password, will be logged in the shell history.</p>
</div></blockquote>
<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>
<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>
<span class="c1">-- https://docs.djangoproject.com/en/dev/ref/databases/#optimizing-postgresql-s-configuration</span>
<span class="k">ALTER</span> <span class="k">ROLE</span> <span class="n">evennia</span> <span class="k">SET</span> <span class="n">client_encoding</span> <span class="k">TO</span> <span class="s1">&#39;utf8&#39;</span><span class="p">;</span>
<span class="k">ALTER</span> <span class="k">ROLE</span> <span class="n">evennia</span> <span class="k">SET</span> <span class="n">default_transaction_isolation</span> <span class="k">TO</span> <span class="s1">&#39;read committed&#39;</span><span class="p">;</span>
<span class="k">ALTER</span> <span class="k">ROLE</span> <span class="n">evennia</span> <span class="k">SET</span> <span class="n">timezone</span> <span class="k">TO</span> <span class="s1">&#39;UTC&#39;</span><span class="p">;</span>
<span class="k">GRANT</span> <span class="k">ALL</span> <span class="k">PRIVILEGES</span> <span class="k">ON</span> <span class="k">DATABASE</span> <span class="n">evennia</span> <span class="k">TO</span> <span class="n">evennia</span><span class="p">;</span>
<span class="c1">-- Other useful commands: </span>
<span class="c1">-- \l (list all databases and permissions)</span>
<span class="c1">-- \q (exit)</span>
</pre></div>
</td></tr></table></div>
<p><a class="reference external" href="https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546">Here</a> is a cheat-sheet for psql commands.</p>
<p>We create a database user ‘evennia’ and a new database named <code class="docutils literal notranslate"><span class="pre">evennia</span></code> (you can call them whatever
you want though). We then grant the ‘evennia’ user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
<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">
<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>
<span class="c1"># PostgreSQL Database Configuration</span>
<span class="c1">#</span>
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">&#39;ENGINE&#39;</span><span class="p">:</span> <span class="s1">&#39;django.db.backends.postgresql_psycopg2&#39;</span><span class="p">,</span>
<span class="s1">&#39;NAME&#39;</span><span class="p">:</span> <span class="s1">&#39;evennia&#39;</span><span class="p">,</span>
<span class="s1">&#39;USER&#39;</span><span class="p">:</span> <span class="s1">&#39;evennia&#39;</span><span class="p">,</span>
<span class="s1">&#39;PASSWORD&#39;</span><span class="p">:</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">,</span>
<span class="s1">&#39;HOST&#39;</span><span class="p">:</span> <span class="s1">&#39;localhost&#39;</span><span class="p">,</span>
<span class="s1">&#39;PORT&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span> <span class="c1"># use default</span>
<span class="p">}}</span>
</pre></div>
</td></tr></table></div>
<p>If you used some other name for the database and user, enter those instead. Run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">migrate</span>
</pre></div>
</div>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on
also use</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">dbshell</span>
</pre></div>
</div>
<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>
<div class="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">
<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
will find what they need from the <a class="reference external" href="https://www.mysql.com/downloads/">MySQL downloads</a> or <a class="reference external" href="https://mariadb.org/download/">MariaDB
downloads</a> pages. You also need the respective database clients
(<code class="docutils literal notranslate"><span class="pre">mysql</span></code>, <code class="docutils literal notranslate"><span class="pre">mariadb-client</span></code>), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.</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
</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>
<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>
<span class="k">GRANT</span> <span class="k">ALL</span> <span class="k">PRIVILEGES</span> <span class="k">ON</span> <span class="n">evennia</span><span class="p">.</span><span class="o">*</span> <span class="k">TO</span> <span class="s1">&#39;evennia&#39;</span><span class="o">@</span><span class="s1">&#39;localhost&#39;</span><span class="p">;</span>
<span class="n">FLUSH</span> <span class="k">PRIVILEGES</span><span class="p">;</span>
<span class="c1">-- use &#39;exit&#39; to quit client</span>
</pre></div>
</td></tr></table></div>
<p><a class="reference external" href="https://gist.github.com/hofmannsven/9164408">Here</a> is a mysql command cheat sheet.</p>
<p>Above we created a new local user and database (we called both ‘evennia’ here, you can name them
what you prefer). We set the character set to <code class="docutils literal notranslate"><span class="pre">utf8</span></code> to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the ‘evennia’ user all privileges on the
<code class="docutils literal notranslate"><span class="pre">evennia</span></code> database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.</p>
<blockquote>
<div><p>Note: If you are not using MySQL for anything else you might consider granting the ‘evennia’ user
full privileges with <code class="docutils literal notranslate"><span class="pre">GRANT</span> <span class="pre">ALL</span> <span class="pre">PRIVILEGES</span> <span class="pre">ON</span> <span class="pre">*.*</span> <span class="pre">TO</span> <span class="pre">'evennia'&#64;'localhost';</span></code>. If you do, it means
you can use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">dbshell</span></code> later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.</p>
</div></blockquote>
</div>
</div>
<div class="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>
<blockquote>
<div><p>Note: The Django documentation suggests using an external <code class="docutils literal notranslate"><span class="pre">db.cnf</span></code> or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. <a class="reference external" href="https://git.io/vQdiN">issue
#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>
<span class="c1"># MySQL Database Configuration</span>
<span class="c1">#</span>
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">&#39;ENGINE&#39;</span><span class="p">:</span> <span class="s1">&#39;django.db.backends.mysql&#39;</span><span class="p">,</span>
<span class="s1">&#39;NAME&#39;</span><span class="p">:</span> <span class="s1">&#39;evennia&#39;</span><span class="p">,</span>
<span class="s1">&#39;USER&#39;</span><span class="p">:</span> <span class="s1">&#39;evennia&#39;</span><span class="p">,</span>
<span class="s1">&#39;PASSWORD&#39;</span><span class="p">:</span> <span class="s1">&#39;somepassword&#39;</span><span class="p">,</span>
<span class="s1">&#39;HOST&#39;</span><span class="p">:</span> <span class="s1">&#39;localhost&#39;</span><span class="p">,</span> <span class="c1"># or an IP Address that your DB is hosted on</span>
<span class="s1">&#39;PORT&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="c1"># use default port</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</td></tr></table></div>
<p>Change this to fit your database setup. Next, run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">migrate</span>
</pre></div>
</div>
<p>to populate your database. Should you ever want to inspect the database directly you can from now on
also use</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">dbshell</span>
</pre></div>
</div>
<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">
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Choosing An SQL Server</a><ul>
<li><a class="reference internal" href="#sqlite3">SQLite3</a><ul>
<li><a class="reference internal" href="#install-of-sqlite3">Install of SQlite3</a></li>
</ul>
</li>
<li><a class="reference internal" href="#postgresql">PostgreSQL</a><ul>
<li><a class="reference internal" href="#install-and-initial-setup-of-postgresql">Install and initial setup of PostgreSQL</a></li>
<li><a class="reference internal" href="#evennia-postgresql-configuration">Evennia PostgreSQL configuration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mysql-mariadb">MySQL / MariaDB</a><ul>
<li><a class="reference internal" href="#installing-and-initial-setup-of-mysql-mariadb">Installing and initial setup of MySQL/MariaDB</a></li>
</ul>
</li>
<li><a class="reference internal" href="#add-mysql-configuration-to-evennia">Add MySQL configuration to Evennia</a></li>
<li><a class="reference internal" href="#others">Others</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Choosing-An-SQL-Server.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Choosing-An-SQL-Server.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Choosing An SQL Server</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,183 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Client Support Grid</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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 Evennia-specific knowledge about the various clients and protocols used.
Everyone’s welcome to report their findings.</p>
<div class="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. If it’s only available for a specific OS, it should be noted
here too.</p></li>
<li><p><strong>Version</strong>: Which version or range of client versions were tested.</p></li>
<li><p><strong>Comments</strong>: Any comments or quirks on using this client with Evennia should be added here. Also
note if some other protocol than Telnet is used (like Websockets, SSH etc).</p></li>
</ul>
</div>
<div class="section" id="client-grid">
<h2>Client Grid<a class="headerlink" href="#client-grid" title="Permalink to this headline"></a></h2>
<p>Name | Version | Comments
:———-:————
<a class="reference external" href="https://github.com/evennia/evennia/wiki/Web%20features#web-client">Evennia webclient</a> | 0.6 | Uses WS/AJAX. <a class="reference external" href="https://github.com/evennia/evennia/issues?utf8=%E2%9C%93&amp;q=client+status%3Dopen+%5D">Current client issues</a>
<a class="reference external" href="http://tintin.sourceforge.net/">tintin++</a> | 2.0+ | No MXP support
<a class="reference external" href="http://tinyfugue.sourceforge.net/">tinyfugue</a> | 5.0+ | No UTF-8 support
<a class="reference external" href="http://mushclient.com/">MUSHclient</a> (Win) | 4.94 | NAWS reports full text area
<a class="reference external" href="http://forums.zuggsoft.com/index.php?page=4&amp;action=file&amp;file_id=65">Zmud</a> (Win) | 7.21 | <em>UNTESTED</em><br /><a class="reference external" href="http://forums.zuggsoft.com/index.php?page=4&amp;action=category&amp;cat_id=11">Cmud</a> (Win) | v3 | <em>UNTESTED</em><br /><a class="reference external" href="http://www.potatomushclient.com/">Potato</a> | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand
“localhost”, must use <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>. <a class="reference external" href="https://github.com/evennia/evennia/issues/1131">Newline issue</a>.
*Won’t send a single blank line on Enter press.
<a class="reference external" href="http://www.mudlet.org/">Mudlet</a> | 3.4+ | No known issues. Some older versions showed &lt;&gt; as html under MXP.
<a class="reference external" href="https://archive.org/details/tucows_196173_SimpleMU_MU_Client">SimpleMU</a> (Win) | full | <em>UNTESTED</em>. Discontinued. NAWS reports pixel size.
<a class="reference external" href="http://www.riverdark.net/atlantis/">Atlantis</a> (Mac) | 0.9.9.4 | No known issues.
<a class="reference external" href="https://sourceforge.net/projects/g-mud/">GMUD</a> | 0.0.1 | Can’t handle any telnet handshakes. Not recommended.
<a class="reference external" href="http://www.beipmu.com/">BeipMU</a> (Win) | 3.0.255 | No MXP support. Best to enable “MUD prompt handling”, disable
“Handle HTML tags”.
<a class="reference external" href="https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072">MudRammer</a> (IOS) | 1.8.7 | Bad Telnet Protocol compliance: displays spurious characters.
<a class="reference external" href="https://itunes.apple.com/us/app/mudmaster/id341160033">MUDMaster</a> (IOS) | 1.3.1 | <em>UNTESTED</em>
<a class="reference external" href="http://bt.happygoatstudios.com/">BlowTorch</a> (Andr) | 1.1.3 | *Telnet NOP displays as spurious character.
<a class="reference external" href="https://play.google.com/store/apps/details?id=com.crap.mukluk">Mukluk</a> (Andr) | 2015.11.20| *Telnet NOP displays as spurious character. Has UTF-8/Emoji
support.
<a class="reference external" href="https://github.com/GNOME/gnome-mud">Gnome-MUD</a> (Unix) | 0.11.2 | Telnet handshake errors. First (only) attempt at logging in
fails.
<a class="reference external" href="https://spyrit.ierne.eu.org/">Spyrit</a> | 0.4 | No MXP, OOB support.
<a class="reference external" href="http://jamochamud.org/">JamochaMUD</a> | 5.2 | Does not support ANSI within MXP text.
<a class="reference external" href="http://duckclient.com/">DuckClient</a> (Chrome)| 4.2 | No MXP support. Displays Telnet Go-Ahead and WILL SUPPRESS-GO-AHEAD
as ù character. Also seems to run the <code class="docutils literal notranslate"><span class="pre">version</span></code> command on connection, which will not work in
<code class="docutils literal notranslate"><span class="pre">MULTISESSION_MODES</span></code> above 1.
<a class="reference external" href="https://www.kildclient.org/">KildClient</a> | 2.11.1 | No known issues.</p>
</div>
<div class="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">
<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">
<li><p><a class="reference external" href="http://bt.happygoatstudios.com/">BlowTorch</a> (Andr)</p></li>
<li><p><a class="reference external" href="https://play.google.com/store/apps/details?id=com.crap.mukluk">Mukluk</a> (Andr)</p></li>
</ul>
<p>Workaround:</p>
<ul class="simple">
<li><p>Set the command in game to <code class="docutils literal notranslate"><span class="pre">&#64;option</span> <span class="pre">NOPKEEPALIVE=off</span></code> for the session, or use the <code class="docutils literal notranslate"><span class="pre">/save</span></code>
parameter to disable it for that Evennian 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 class="section" id="issue-won-t-send-blank-line-on-enter-key-press">
<h3>Issue: Won’t send blank line on Enter key press.<a class="headerlink" href="#issue-won-t-send-blank-line-on-enter-key-press" title="Permalink to this headline"></a></h3>
<p>Known clients:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.potatomushclient.com/">Potato</a></p></li>
</ul>
<p>Workaround:</p>
<ul class="simple">
<li><p>Press Control Enter, then Enter key again to send blank line.</p></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Client Support Grid</a><ul>
<li><a class="reference internal" href="#legend">Legend:</a></li>
<li><a class="reference internal" href="#client-grid">Client Grid</a></li>
<li><a class="reference internal" href="#workarounds-for-client-issues">Workarounds for client issues:</a><ul>
<li><a class="reference internal" href="#issue-telnet-nop-displays-as-spurious-character">Issue: Telnet NOP displays as spurious character.</a></li>
<li><a class="reference internal" href="#issue-won-t-send-blank-line-on-enter-key-press">Issue: Won’t send blank line on Enter key press.</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Client-Support-Grid.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Client-Support-Grid.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Client Support Grid</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,192 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Game Index</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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>
<ul class="simple">
<li><p>also if you have just started development and don’t yet accept external
players. It’s a chance for us to know you are out there and for you to make us
intrigued about or excited for your upcoming game!</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">
<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>
</pre></div>
</div>
<p>This will start the Evennia <em>Connection wizard</em>. From the menu, select to add
your game to the Evennia Game Index. Follow the prompts and don’t forget to
save your new settings in the end. Use <code class="docutils literal notranslate"><span class="pre">quit</span></code> at any time if you change your
mind.</p>
<blockquote>
<div><p>The wizard will create a new file <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/connection_settings.py</span></code>
with the settings you chose. This is imported from the end of your main
settings file and will thus override it. You can edit this new file if you
want, but remember that if you run the wizard again, your changes may get
over-written.</p>
</div></blockquote>
</div>
<div class="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="bp">True</span>
<span class="n">GAME_INDEX_LISTING</span> <span class="o">=</span> <span class="p">{</span>
<span class="c1"># required </span>
<span class="s1">&#39;game_status&#39;</span><span class="p">:</span> <span class="s1">&#39;pre-alpha&#39;</span><span class="p">,</span> <span class="c1"># pre-alpha, alpha, beta, launched</span>
<span class="s1">&#39;listing_contact&#39;</span><span class="p">:</span> <span class="s2">&quot;dummy@dummy.com&quot;</span><span class="p">,</span> <span class="c1"># not publicly shown.</span>
<span class="s1">&#39;short_description&#39;</span><span class="p">:</span> <span class="s1">&#39;Short blurb&#39;</span><span class="p">,</span>
<span class="c1"># optional </span>
<span class="s1">&#39;long_description&#39;</span><span class="p">:</span>
<span class="s2">&quot;Longer description that can use Markdown like *bold*, _italic_&quot;</span>
<span class="s2">&quot;and [linkname](http://link.com). Use </span><span class="se">\n</span><span class="s2"> for line breaks.&quot;</span>
<span class="s1">&#39;telnet_hostname&#39;</span><span class="p">:</span> <span class="s1">&#39;dummy.com&#39;</span><span class="p">,</span>
<span class="s1">&#39;telnet_port&#39;</span><span class="p">:</span> <span class="s1">&#39;1234&#39;</span><span class="p">,</span>
<span class="s1">&#39;web_client_url&#39;</span><span class="p">:</span> <span class="s1">&#39;dummy.com/webclient&#39;</span><span class="p">,</span>
<span class="s1">&#39;game_website&#39;</span><span class="p">:</span> <span class="s1">&#39;dummy.com&#39;</span><span class="p">,</span>
<span class="c1"># &#39;game_name&#39;: &#39;MyGame&#39;, # set only if different than settings.SERVERNAME</span>
<span class="p">}</span>
</pre></div>
</td></tr></table></div>
<p>Of these, the <code class="docutils literal notranslate"><span class="pre">game_status</span></code>, <code class="docutils literal notranslate"><span class="pre">short_description</span></code> and <code class="docutils literal notranslate"><span class="pre">listing_contact</span></code> are
required. The <code class="docutils literal notranslate"><span class="pre">listing_contact</span></code> is not publicly visible and is only meant as a
last resort if we need to get in touch with you over any listing issue/bug (so
far this has never happened).</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">
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Evennia Game Index</a><ul>
<li><a class="reference internal" href="#connect-with-the-wizard">Connect with the wizard</a></li>
<li><a class="reference internal" href="#manual-settings">Manual Settings</a></li>
<li><a class="reference internal" href="#non-public-games">Non-public games</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Evennia-Game-Index.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Evennia-Game-Index.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Game Index</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,595 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Getting Started</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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>
<div><p>Note: You don’t need to make anything visible to the ‘net in order to run and
test out Evennia. Apart from downloading and updating you don’t even need an
internet connection until you feel ready to share your game with the world.</p>
</div></blockquote>
<ul class="simple">
<li><p><a class="reference external" href="Setup/Getting-Started#quick-start">Quick Start</a></p></li>
<li><p><a class="reference external" href="Setup/Getting-Started#requirements">Requirements</a></p></li>
<li><p><a class="reference external" href="Setup/Getting-Started#linux-install">Linux Install</a></p></li>
<li><p><a class="reference external" href="Setup/Getting-Started#mac-install">Mac Install</a></p></li>
<li><p><a class="reference external" href="Setup/Getting-Started#windows-install">Windows Install</a></p></li>
<li><p><a class="reference internal" href="Running-Evennia-in-Docker.html"><span class="doc">Running in Docker</span></a></p></li>
<li><p><a class="reference external" href="Setup/Getting-Started#where-to-go-next">Where to Go Next</a></p></li>
<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">
<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>
<ol class="simple">
<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">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>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">mygame</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code> (make sure to make a superuser when asked)
Evennia should now be running and you can connect to it by pointing a web browser to
<code class="docutils literal notranslate"><span class="pre">http://localhost:4001</span></code> or a MUD telnet client to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code> (use <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code> if your OS does
not recognize <code class="docutils literal notranslate"><span class="pre">localhost</span></code>).</p></li>
</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">
<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>
<ul class="simple">
<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>
<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>
</ul>
</li>
<li><p><a class="reference external" href="http://git-scm.com/">GIT</a> - version control software for getting and
updating Evennia itself - Mac users can use the
<a class="reference external" href="http://code.google.com/p/git-osx-installer/">git-osx-installer</a> or the
<a class="reference external" href="http://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">MacPorts version</a>.</p></li>
<li><p><a class="reference external" href="http://twistedmatrix.com">Twisted</a> (v19.0+)</p>
<ul>
<li><p><a class="reference external" href="http://www.zope.org/Products/ZopeInterface">ZopeInterface</a> (v3.0+) - usually included in
Twisted packages</p></li>
<li><p>Linux/Mac users may need the <code class="docutils literal notranslate"><span class="pre">gcc</span></code> and <code class="docutils literal notranslate"><span class="pre">python-dev</span></code> packages or equivalent.</p></li>
<li><p>Windows users need <a class="reference external" href="https://aka.ms/vs/16/release/vs_buildtools.exe">MS Visual C++</a> and <em>maybe</em>
<a class="reference external" href="https://pypi.python.org/pypi/pypiwin32">pypiwin32</a>.</p></li>
</ul>
</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">
<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>
<p>For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the <a class="reference external" href="Setup/Getting-Started#requirements">dependencies</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</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">python3</span><span class="o">-</span><span class="n">git</span>
<span class="n">python3</span><span class="o">-</span><span class="n">virtualenv</span> <span class="n">gcc</span>
<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>
</pre></div>
</div>
<p>Note that, the default Python version for your distribution may still not be Python3.7 after this.
This is ok - we’ll specify exactly which Python to use later.
You should make sure to <em>not</em> be <code class="docutils literal notranslate"><span class="pre">root</span></code> after this step, running as <code class="docutils literal notranslate"><span class="pre">root</span></code> is a
security risk. Now create a folder where you want to do all your Evennia
development:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">muddev</span>
<span class="n">cd</span> <span class="n">muddev</span>
</pre></div>
</div>
<p>Next we fetch Evennia itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>A new folder <code class="docutils literal notranslate"><span class="pre">evennia</span></code> will appear containing the Evennia library. This only
contains the source code though, it is not <em>installed</em> yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a <em>virtualenv</em>. If you are unsure about what a
virtualenv is and why it’s useful, see the <a class="reference external" href="Setup/Glossary#virtualenv">Glossary entry on
virtualenv</a>.</p>
<p>Run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-V</span></code> to see which version of Python your system defaults to.</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"># 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>
</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
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system (or the Linux distro lagging behind
on Python package versions). It will also always use the right version of Python.
Activate the virtualenv:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">source</span> <span class="n">evenv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
</pre></div>
</div>
<p>The text <code class="docutils literal notranslate"><span class="pre">(evenv)</span></code> should appear next to your prompt to show that the virtual
environment is active.</p>
<blockquote>
<div><p>Remember that you need to activate the virtualenv like this <em>every time</em> you
start a new terminal to get access to the Python packages (notably the
important <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program) we are about to install.</p>
</div></blockquote>
<p>Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> and <code class="docutils literal notranslate"><span class="pre">evenv/</span></code>
folders) and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">e</span> <span class="n">evennia</span>
</pre></div>
</div>
<p>For more info about <code class="docutils literal notranslate"><span class="pre">pip</span></code>, see the <a class="reference external" href="Glossary.html#pip">Glossary entry on pip</a>. If
install failed with any issues, see <a class="reference external" href="Setup/Getting-Started#linux-troubleshooting">Linux Troubleshooting</a>.</p>
<p>Next we’ll start our new game, here called “mygame”. This will create yet
another new folder where you will be creating your new game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">init</span> <span class="n">mygame</span>
</pre></div>
</div>
<p>Your final folder structure should look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">muddev</span>
<span class="n">evenv</span><span class="o">/</span>
<span class="n">evennia</span><span class="o">/</span>
<span class="n">mygame</span><span class="o">/</span>
</pre></div>
</div>
<p>You can <a class="reference external" href="Components/Server-Conf.html#settings-file">configure Evennia</a> extensively, for example
to use a <a class="reference internal" href="Choosing-An-SQL-Server.html"><span class="doc">different database</span></a>. For now we’ll just stick
to the defaults though.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">mygame</span>
<span class="n">evennia</span> <span class="n">migrate</span> <span class="c1"># (this creates the database)</span>
<span class="n">evennia</span> <span class="n">start</span> <span class="c1"># (create a superuser when asked. Email is optional.)</span>
</pre></div>
</div>
<blockquote>
<div><p>Server logs are found in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>. To easily view server logs
live in the terminal, use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">-l</span></code> (exit the log-view with Ctrl-C).</p>
</div></blockquote>
<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">
<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
terminal</a>
if you are unsure how it works. If you run into any issues during the
installation, please check out <a class="reference external" href="Setup/Getting-Started#mac-troubleshooting">Mac Troubleshooting</a>.</p>
<ul class="simple">
<li><p>Python should already be installed but you must make sure it’s a high enough version.
(<a class="reference external" href="http://docs.python-guide.org/en/latest/starting/install/osx/">This</a> discusses
how you may upgrade it). Remember that you need Python3.7, not Python2.7!</p></li>
<li><p>GIT can be obtained with
<a class="reference external" href="http://code.google.com/p/git-osx-installer/">git-osx-installer</a> or via
MacPorts <a class="reference external" href="http://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">as described
here</a>.</p></li>
<li><p>If you run into issues with installing <code class="docutils literal notranslate"><span class="pre">Twisted</span></code> later you may need to
install gcc and the Python headers.</p></li>
</ul>
<p>After this point you should not need <code class="docutils literal notranslate"><span class="pre">sudo</span></code> or any higher privileges to install anything.</p>
<p>Now create a folder where you want to do all your Evennia development:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">muddev</span>
<span class="n">cd</span> <span class="n">muddev</span>
</pre></div>
</div>
<p>Next we fetch Evennia itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>A new folder <code class="docutils literal notranslate"><span class="pre">evennia</span></code> will appear containing the Evennia library. This only
contains the source code though, it is not <em>installed</em> yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a <em>virtualenv</em>. If you are unsure about what a
virtualenv is and why it’s useful, see the <a class="reference external" href="Glossary.html#virtualenv">Glossary entry on virtualenv</a>.</p>
<p>Run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-V</span></code> to check which Python your system defaults to.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># If your Mac defaults to Python3:</span>
<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>
</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
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">source</span> <span class="n">evenv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
</pre></div>
</div>
<p>The text <code class="docutils literal notranslate"><span class="pre">(evenv)</span></code> should appear next to your prompt to show the virtual
environment is active.</p>
<blockquote>
<div><p>Remember that you need to activate the virtualenv like this <em>every time</em> you
start a new terminal to get access to the Python packages (notably the
important <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program) we are about to install.</p>
</div></blockquote>
<p>Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> and <code class="docutils literal notranslate"><span class="pre">evenv/</span></code>
folders) and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="c1"># Old pip versions may be an issue on Mac.</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">setuptools</span> <span class="c1"># Ditto concerning Mac issues.</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">e</span> <span class="n">evennia</span>
</pre></div>
</div>
<p>For more info about <code class="docutils literal notranslate"><span class="pre">pip</span></code>, see the <a class="reference external" href="Glossary.html#pip">Glossary entry on pip</a>. If
install failed with any issues, see <a class="reference external" href="Setup/Getting-Started#mac-troubleshooting">Mac Troubleshooting</a>.</p>
<p>Next we’ll start our new game. We’ll call it “mygame” here. This creates a new
folder where you will be creating your new game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">init</span> <span class="n">mygame</span>
</pre></div>
</div>
<p>Your final folder structure should look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">muddev</span>
<span class="n">evenv</span><span class="o">/</span>
<span class="n">evennia</span><span class="o">/</span>
<span class="n">mygame</span><span class="o">/</span>
</pre></div>
</div>
<p>You can <a class="reference external" href="Components/Server-Conf.html#settings-file">configure Evennia</a> extensively, for example
to use a <a class="reference internal" href="Choosing-An-SQL-Server.html"><span class="doc">different database</span></a>. We’ll go with the
defaults here.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">mygame</span>
<span class="n">evennia</span> <span class="n">migrate</span> <span class="c1"># (this creates the database)</span>
<span class="n">evennia</span> <span class="n">start</span> <span class="c1"># (create a superuser when asked. Email is optional.)</span>
</pre></div>
</div>
<blockquote>
<div><p>Server logs are found in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>. To easily view server logs
live in the terminal, use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">-l</span></code> (exit the log-view with Ctrl-C).</p>
</div></blockquote>
<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">
<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>
<blockquote>
<div><p>If you are running Windows10, consider using the Windows Subsystem for Linux
(<a class="reference external" href="https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux">WSL</a>) instead.
You should then follow the Linux install instructions above.</p>
</div></blockquote>
<p>The Evennia server itself is a command line program. In the Windows launch
menu, start <em>All Programs -&gt; Accessories -&gt; command prompt</em> and you will get
the Windows command line interface. Here is <a class="reference external" href="http://www.bleepingcomputer.com/tutorials/windows-command-prompt-introduction/">one of many tutorials on using the Windows command
line</a>
if you are unfamiliar with it.</p>
<ul class="simple">
<li><p>Install Python <a class="reference external" href="https://www.python.org/downloads/windows/">from the Python homepage</a>. You will
need to be a
Windows Administrator to install packages. You want Python version <strong>3.7.0</strong> (latest verified
version), usually
the 64-bit version (although it doesn’t matter too much). <strong>When installing, make sure
to check-mark <em>all</em> install options, especially the one about making Python
available on the path (you may have to scroll to see it)</strong>. This allows you to
just write <code class="docutils literal notranslate"><span class="pre">python</span></code> in any console without first finding where the <code class="docutils literal notranslate"><span class="pre">python</span></code>
program actually sits on your hard drive.</p></li>
<li><p>You need to also get <a class="reference external" href="http://git-scm.com/downloads">GIT</a> and install it. You
can use the default install options but when you get asked to “Adjust your PATH
environment”, you should select the second option “Use Git from the Windows
Command Prompt”, which gives you more freedom as to where you can use the
program.</p></li>
<li><p>Finally you must install the <a class="reference external" href="https://aka.ms/vs/16/release/vs_buildtools.exe">Microsoft Visual C++ compiler for
Python</a>. Download and run the linked installer and
install the C++ tools. Keep all the defaults. Allow the install of the “Win10 SDK”, even if you are
on Win7 (not tested on older Windows versions). If you later have issues with installing Evennia due
to a failure to build the “Twisted wheels”, this is where you are missing things.</p></li>
<li><p>You <em>may</em> need the <a class="reference external" href="https://pypi.python.org/pypi/pypiwin32">pypiwin32</a> Python headers. Install
these only if you have issues.</p></li>
</ul>
<p>You can install Evennia wherever you want. <code class="docutils literal notranslate"><span class="pre">cd</span></code> to that location and create a
new folder for all your Evennia development (let’s call it <code class="docutils literal notranslate"><span class="pre">muddev</span></code>).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">muddev</span>
<span class="n">cd</span> <span class="n">muddev</span>
</pre></div>
</div>
<blockquote>
<div><p>Hint: If <code class="docutils literal notranslate"><span class="pre">cd</span></code> isn’t working you can use <code class="docutils literal notranslate"><span class="pre">pushd</span></code> instead to force the
directory change.</p>
</div></blockquote>
<p>Next we fetch Evennia itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>A new folder <code class="docutils literal notranslate"><span class="pre">evennia</span></code> will appear containing the Evennia library. This only
contains the source code though, it is not <em>installed</em> yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a <em>virtualenv</em>. If you are unsure about what a
virtualenv is and why it’s useful, see the <a class="reference external" href="Glossary.html#virtualenv">Glossary entry on virtualenv</a>.</p>
<p>In your console, try <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-V</span></code> to see which version of Python your system
defaults to.</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">virtualenv</span>
<span class="c1"># If your setup defaults to Python3.7:</span>
<span class="n">virtualenv</span> <span class="n">evenv</span>
<span class="c1"># If your setup defaults to Python2, specify path to python3.exe explicitly:</span>
<span class="n">virtualenv</span> <span class="o">-</span><span class="n">p</span> <span class="n">C</span><span class="p">:</span>\<span class="n">Python37</span>\<span class="n">python</span><span class="o">.</span><span class="n">exe</span> <span class="n">evenv</span>
<span class="c1"># If you get an infinite spooling response, press CTRL + C to interrupt and try using:</span>
<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">venv</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
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># If you are using a standard command prompt, you can use the following:</span>
<span class="n">evenv</span>\<span class="n">scripts</span>\<span class="n">activate</span><span class="o">.</span><span class="n">bat</span>
<span class="c1"># If you are using a PS Shell, Git Bash, or other, you can use the following:</span>
<span class="o">.</span>\<span class="n">evenv</span>\<span class="n">scripts</span>\<span class="n">activate</span>
</pre></div>
</div>
<p>The text <code class="docutils literal notranslate"><span class="pre">(evenv)</span></code> should appear next to your prompt to show the virtual
environment is active.</p>
<blockquote>
<div><p>Remember that you need to activate the virtualenv like this <em>every time</em> you
start a new console window if you want to get access to the Python packages
(notably the important <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program) we are about to install.</p>
</div></blockquote>
<p>Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> and <code class="docutils literal notranslate"><span class="pre">evenv</span></code>
folders when you use the <code class="docutils literal notranslate"><span class="pre">dir</span></code> command) and run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">e</span> <span class="n">evennia</span>
</pre></div>
</div>
<p>For more info about <code class="docutils literal notranslate"><span class="pre">pip</span></code>, see the <a class="reference external" href="Glossary.html#pip">Glossary entry on pip</a>. If
the install failed with any issues, see [Windows Troubleshooting](Getting-Started#windows-
troubleshooting).
Next we’ll start our new game, we’ll call it “mygame” here. This creates a new folder where you will
be
creating your new game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">init</span> <span class="n">mygame</span>
</pre></div>
</div>
<p>Your final folder structure should look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">path</span>\<span class="n">to</span>\<span class="n">muddev</span>
<span class="n">evenv</span>\
<span class="n">evennia</span>\
<span class="n">mygame</span>\
</pre></div>
</div>
<p>You can <a class="reference external" href="Components/Server-Conf.html#settings-file">configure Evennia</a> extensively, for example
to use a <a class="reference internal" href="Choosing-An-SQL-Server.html"><span class="doc">different database</span></a>. We’ll go with the
defaults here.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">mygame</span>
<span class="n">evennia</span> <span class="n">migrate</span> <span class="c1"># (this creates the database)</span>
<span class="n">evennia</span> <span class="n">start</span> <span class="c1"># (create a superuser when asked. Email is optional.)</span>
</pre></div>
</div>
<blockquote>
<div><p>Server logs are found in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>. To easily view server logs
live in the terminal, use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">-l</span></code> (exit the log-view with Ctrl-C).</p>
</div></blockquote>
<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="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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@batchcommand</span> <span class="n">tutorial_world</span><span class="o">.</span><span class="n">build</span>
</pre></div>
</div>
<p>to build <a class="reference internal" href="../Howto/Starting/Part1/Tutorial-World-Introduction.html"><span class="doc">Evennia’s tutorial world</span></a> - it’s a small solo quest to
explore. Only run the instructed <code class="docutils literal notranslate"><span class="pre">&#64;batchcommand</span></code> once. You’ll get a lot of text scrolling by as the
tutorial is built. Once done, the <code class="docutils literal notranslate"><span class="pre">tutorial</span></code> exit will have appeared out of Limbo - just write
<code class="docutils literal notranslate"><span class="pre">tutorial</span></code> to enter it.</p>
<p>Once you get back to <code class="docutils literal notranslate"><span class="pre">Limbo</span></code> from the tutorial (if you get stuck in the tutorial quest you can do
<code class="docutils literal notranslate"><span class="pre">&#64;tel</span> <span class="pre">#2</span></code> to jump to Limbo), a good idea is to learn how to [start, stop and reload](Start-Stop-
Reload) the Evennia server. You may also want to familiarize yourself with some
<a class="reference internal" href="../Glossary.html"><span class="doc">commonly used terms in our Glossary</span></a>. After that, why not experiment with
<a class="reference internal" href="../Howto/Starting/Part1/Building-Quickstart.html"><span class="doc">creating some new items and build some new rooms</span></a> out from Limbo.</p>
<p>From here on, you could move on to do one of our <a class="reference internal" href="../Howto/Howto-Overview.html"><span class="doc">introductory tutorials</span></a> or simply dive
headlong into Evennia’s comprehensive <a class="reference external" href="https://github.com/evennia/evennia/wiki">manual</a>. While
Evennia has no major game systems out of the box, we do supply a range of optional <em>contribs</em> that
you can use or borrow from. They range from dice rolling and alternative color schemes to barter and
combat systems. You can find the <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md">growing list of contribs
here</a>.</p>
<p>If you have any questions, you can always ask in <a class="reference external" href="http://webchat.freenode.net/?channels=evennia&amp;uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb">the developer
chat</a>
<code class="docutils literal notranslate"><span class="pre">#evennia</span></code> on <code class="docutils literal notranslate"><span class="pre">irc.freenode.net</span></code> or by posting to the <a class="reference external" href="https://groups.google.com/forum/#%21forum/evennia">Evennia
forums</a>. You can also join the <a class="reference external" href="https://discord.gg/NecFePw">Discord
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">
<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
covered here, <a class="reference external" href="https://github.com/evennia/evennia/issues">please report it</a>
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">
<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
failing to include <code class="docutils literal notranslate"><span class="pre">Python.h</span></code>) then try <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python3-setuptools</span> <span class="pre">python3-dev</span></code>.
Once installed, run <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> again.</p></li>
<li><p>Under some not-updated Linux distributions you may run into errors with a
too-old <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> or missing <code class="docutils literal notranslate"><span class="pre">functools</span></code>. If so, update your environment
with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">pip</span> <span class="pre">wheel</span> <span class="pre">setuptools</span></code>. Then try <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> again.</p></li>
<li><p>One user reported a rare issue on Ubuntu 16 is an install error on installing Twisted; <code class="docutils literal notranslate"><span class="pre">Command</span> <span class="pre">&quot;python</span> <span class="pre">setup.py</span> <span class="pre">egg_info&quot;</span> <span class="pre">failed</span> <span class="pre">with</span> <span class="pre">error</span> <span class="pre">code</span> <span class="pre">1</span> <span class="pre">in</span> <span class="pre">/tmp/pip-build-vnIFTg/twisted/</span></code> with errors
like <code class="docutils literal notranslate"><span class="pre">distutils.errors.DistutilsError:</span> <span class="pre">Could</span> <span class="pre">not</span> <span class="pre">find</span> <span class="pre">suitable</span> <span class="pre">distribution</span> <span class="pre">for</span> <span class="pre">Requirement.parse('incremental&gt;=16.10.1')</span></code>. This appears possible to solve by simply updating Ubuntu
with <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">update</span> <span class="pre">&amp;&amp;</span> <span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">dist-upgrade</span></code>.</p></li>
<li><p>Users of Fedora (notably Fedora 24) has reported a <code class="docutils literal notranslate"><span class="pre">gcc</span></code> error saying the directory
<code class="docutils literal notranslate"><span class="pre">/usr/lib/rpm/redhat/redhat-hardened-cc1</span></code> is missing, despite <code class="docutils literal notranslate"><span class="pre">gcc</span></code> itself being installed. <a class="reference external" href="https://gist.github.com/yograterol/99c8e123afecc828cb8c">The
confirmed work-around</a> seems to be to
install the <code class="docutils literal notranslate"><span class="pre">redhat-rpm-config</span></code> package with e.g. <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">dnf</span> <span class="pre">install</span> <span class="pre">redhat-rpm-config</span></code>.</p></li>
<li><p>Some users trying to set up a virtualenv on an NTFS filesystem find that it fails due to issues
with symlinks not being supported. Answer is to not use NTFS (seriously, why would you do that to
yourself?)</p></li>
</ul>
</div>
<div class="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
version below <code class="docutils literal notranslate"><span class="pre">2.7.12</span></code>. If you get this error, update to the latest XCode and Python2 version.</p></li>
<li><p>Some Mac users have reported not being able to connect to <code class="docutils literal notranslate"><span class="pre">localhost</span></code> (i.e. your own computer). If
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">
<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
you might have missed installing Python on the path. In the Windows Python installer you get a list
of options for what to install. Most or all options are pre-checked except this one, and you may
even have to scroll down to see it. Reinstall Python and make sure it’s checked.</p></li>
<li><p>If your MUD client cannot connect to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code>, try the equivalent <code class="docutils literal notranslate"><span class="pre">127.0.0.1:4000</span></code>
instead. Some MUD clients on Windows does not appear to understand the alias <code class="docutils literal notranslate"><span class="pre">localhost</span></code>.</p></li>
<li><p>If you run <code class="docutils literal notranslate"><span class="pre">virtualenv</span> <span class="pre">evenv</span></code> and get a <code class="docutils literal notranslate"><span class="pre">'virtualenv'</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">recognized</span> <span class="pre">as</span> <span class="pre">an</span> <span class="pre">internal</span> <span class="pre">or</span> <span class="pre">external</span> <span class="pre">command,</span> <span class="pre">operable</span> <span class="pre">program</span> <span class="pre">or</span> <span class="pre">batch</span> <span class="pre">file.</span></code> error, you can <code class="docutils literal notranslate"><span class="pre">mkdir</span> <span class="pre">evenv</span></code>, <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">evenv</span></code> and then <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">virtualenv</span> <span class="pre">.</span></code> as a workaround.</p></li>
<li><p>Some Windows users get an error installing the Twisted ‘wheel’. A wheel is a pre-compiled binary
package for Python. A common reason for this error is that you are using a 32-bit version of Python,
but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a
slightly older Twisted version. So if, say, version <code class="docutils literal notranslate"><span class="pre">18.1</span></code> failed, install <code class="docutils literal notranslate"><span class="pre">18.0</span></code> manually with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">twisted==18.0</span></code>. Alternatively you could try to get a 64-bit version of Python (uninstall the
32bit one). If so, you must then <code class="docutils literal notranslate"><span class="pre">deactivate</span></code> the virtualenv, delete the <code class="docutils literal notranslate"><span class="pre">evenv</span></code> folder and recreate
it anew (it will then use the new Python executable).</p></li>
<li><p>If your server won’t start, with no error messages (and no log files at all when starting from
scratch), try to start with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">ipstart</span></code> instead. If you then see an error about <code class="docutils literal notranslate"><span class="pre">system</span> <span class="pre">cannot</span> <span class="pre">find</span> <span class="pre">the</span> <span class="pre">path</span> <span class="pre">specified</span></code>, it may be that the file <code class="docutils literal notranslate"><span class="pre">evennia/evennia/server/twistd.bat</span></code> has the wrong
path to the <code class="docutils literal notranslate"><span class="pre">twistd</span></code> executable. This file is auto-generated, so try to delete it and then run
<code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code> to rebuild it and see if it works. If it still doesn’t work you need to open it in a
text editor like Notepad. It’s just one line containing the path to the <code class="docutils literal notranslate"><span class="pre">twistd.exe</span></code> executable as
determined by Evennia. If you installed Twisted in a non-standard location this might be wrong and
you should update the line to the real location.</p></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Getting Started</a><ul>
<li><a class="reference internal" href="#quick-start">Quick Start</a></li>
<li><a class="reference internal" href="#requirements">Requirements</a></li>
<li><a class="reference internal" href="#linux-install">Linux Install</a></li>
<li><a class="reference internal" href="#mac-install">Mac Install</a></li>
<li><a class="reference internal" href="#windows-install">Windows Install</a></li>
<li><a class="reference internal" href="#where-to-go-next">Where to Go Next</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#linux-troubleshooting">Linux Troubleshooting</a></li>
<li><a class="reference internal" href="#mac-troubleshooting">Mac Troubleshooting</a></li>
<li><a class="reference internal" href="#windows-troubleshooting">Windows Troubleshooting</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Extended-Installation.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Extended-Installation.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Getting Started</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

167
docs/1.0-dev/Setup/Grapevine.html Normal file
View file

@ -0,0 +1,167 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Grapevine</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyopenssl</span>
</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="bp">True</span>
</pre></div>
</td></tr></table></div>
<p>Next, register an account at https://grapevine.haus. When you have logged in,
go to your Settings/Profile and to the <code class="docutils literal notranslate"><span class="pre">Games</span></code> sub menu. Here you register your
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>
<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>
<p>You can also customize the Grapevine channels you are allowed to connect to. This
is added to the <code class="docutils literal notranslate"><span class="pre">GRAPEVINE_CHANNELS</span></code> setting. You can see which channels are available
by going to the Grapevine online chat here: https://grapevine.haus/chat.</p>
<p>Start/reload Evennia and log in as a privileged user. You should now have a new
command available: <code class="docutils literal notranslate"><span class="pre">&#64;grapevine2chan</span></code>. This command is called like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@grapevine2chan</span><span class="p">[</span><span class="o">/</span><span class="n">switches</span><span class="p">]</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">grapevine_channel</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Here, the <code class="docutils literal notranslate"><span class="pre">evennia_channel</span></code> must be the name of an existing Evennia channel and
<code class="docutils literal notranslate"><span class="pre">grapevine_channel</span></code> one of the supported channels in <code class="docutils literal notranslate"><span class="pre">GRAPEVINE_CHANNELS</span></code>.</p>
<blockquote>
<div><p>At the time of writing, the Grapevine network only has two channels:
<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">
<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
new channel <code class="docutils literal notranslate"><span class="pre">gw</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> @ccreate gw = This is connected to an gw channel!
</pre></div>
</div>
<p>You will automatically join the new channel.</p>
<p>Next we will create a connection to the Grapevine network.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@grapevine2chan</span> <span class="n">gw</span> <span class="o">=</span> <span class="n">gossip</span>
</pre></div>
</div>
<p>Evennia will now create a new connection and connect it to Grapevine. Connect
to https://grapevine.haus/chat to check.</p>
<p>Write something in the Evennia channel <em>gw</em> and check so a message appears in
the Grapevine chat. Write a reply in the chat and the grapevine bot should echo
it to your channel in-game.</p>
<p>Your Evennia gamers can now chat with users on external Grapevine channels!</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Grapevine</a><ul>
<li><a class="reference internal" href="#configuring-grapevine">Configuring Grapevine</a></li>
<li><a class="reference internal" href="#setting-up-grapevine-step-by-step">Setting up Grapevine, step by step</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Grapevine.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Grapevine.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Grapevine</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,163 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">HAProxy Config (Optional)</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Redhat derivatives</span>
<span class="n">yum</span> <span class="n">install</span> <span class="n">haproxy</span>
<span class="c1"># dnf instead of yum for very recent Fedora distros.</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian derivatives</span>
<span class="n">apt</span> <span class="n">install</span> <span class="n">haproxy</span>
</pre></div>
</div>
<p>Configuration of HAProxy requires a single file given as an argument on the command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">haproxy</span> <span class="o">-</span><span class="n">f</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">config</span><span class="o">.</span><span class="n">file</span>
</pre></div>
</div>
<p>In it (example using haproxy 1.5.18 on Centos7):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># stuff provided by the default haproxy installs</span>
<span class="k">global</span>
<span class="n">log</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">log</span> <span class="n">local0</span>
<span class="n">chroot</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">haproxy</span>
<span class="n">maxconn</span> <span class="mi">4000</span>
<span class="n">user</span> <span class="n">haproxy</span>
<span class="n">defaults</span>
<span class="n">mode</span> <span class="n">http</span>
<span class="n">option</span> <span class="n">forwardfor</span>
<span class="c1"># Evennia Specifics</span>
<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">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">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>
</div>
<p>Then edit mygame/server/conf/settings.py and add:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">WEBSERVER_INTERFACES</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;127.0.0.1&#39;</span><span class="p">]</span>
<span class="n">WEBSOCKET_CLIENT_INTERFACE</span> <span class="o">=</span> <span class="s1">&#39;127.0.0.1&#39;</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">LOCKDOWN_MODE</span><span class="o">=</span><span class="kc">True</span>
</pre></div>
</div>
<p>and</p>
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">HAProxy Config (Optional)</a><ul>
<li><a class="reference internal" href="#evennia-https-and-secure-websockets-can-play-nicely-together-quickly">Evennia, HTTPS and Secure Websockets can play nicely together, quickly.</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/HAProxy-Config.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="HAProxy-Config.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">HAProxy Config (Optional)</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,249 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">How to connect Evennia to Twitter</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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>
<p>To tweet from Evennia you will need both the “API Token” and the “API secret” strings as well as the
“Access Token” and “Access Secret” strings.</p>
<p>Twitter changed their requirements to require a Mobile number on the Twitter account to register new
apps with write access. If you’re unable to do this, please see <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">
<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">
<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
them, it can be an idea to go through the <a class="reference internal" href="../Howto/Starting/Part1/Adding-Commands.html"><span class="doc">Adding a Command Tutorial</span></a>
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>
<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>
<span class="c1"># from the Twitter dev site</span>
<span class="n">TWITTER_API</span> <span class="o">=</span> <span class="n">twitter</span><span class="o">.</span><span class="n">Api</span><span class="p">(</span><span class="n">consumer_key</span><span class="o">=</span><span class="s1">&#39;api_key&#39;</span><span class="p">,</span>
<span class="n">consumer_secret</span><span class="o">=</span><span class="s1">&#39;api_secret&#39;</span><span class="p">,</span>
<span class="n">access_token_key</span><span class="o">=</span><span class="s1">&#39;access_token_key&#39;</span><span class="p">,</span>
<span class="n">access_token_secret</span><span class="o">=</span><span class="s1">&#39;access_token_secret&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">CmdTweet</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Tweet a message</span>
<span class="sd"> Usage: </span>
<span class="sd"> tweet &lt;message&gt;</span>
<span class="sd"> This will send a Twitter tweet to a pre-configured Twitter account.</span>
<span class="sd"> A tweet has a maximum length of 280 characters. </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;tweet&quot;</span>
<span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:pperm(tweet) or pperm(Developers)&quot;</span>
<span class="n">help_category</span> <span class="o">=</span> <span class="s2">&quot;Comms&quot;</span>
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s2">&quot;This performs the tweet&quot;</span>
<span class="n">caller</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span>
<span class="n">tweet</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">tweet</span><span class="p">:</span>
<span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: tweet &lt;message&gt;&quot;</span><span class="p">)</span>
<span class="k">return</span>
<span class="n">tlen</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">tweet</span><span class="p">)</span>
<span class="k">if</span> <span class="n">tlen</span> <span class="o">&gt;</span> <span class="mi">280</span><span class="p">:</span>
<span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Your tweet was </span><span class="si">%i</span><span class="s2"> chars long (max 280).&quot;</span> <span class="o">%</span> <span class="n">tlen</span><span class="p">)</span>
<span class="k">return</span>
<span class="c1"># post the tweet </span>
<span class="n">TWITTER_API</span><span class="o">.</span><span class="n">PostUpdate</span><span class="p">(</span><span class="n">tweet</span><span class="p">)</span>
<span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;You tweeted:</span><span class="se">\n</span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">tweet</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>Be sure to substitute your own actual API/Access keys and secrets in the appropriate places.</p>
<p>We default to limiting tweet access to players with <code class="docutils literal notranslate"><span class="pre">Developers</span></code>-level access <em>or</em> to those players
that have the permission “tweet” (allow individual characters to tweet with <code class="docutils literal notranslate"><span class="pre">&#64;perm/player</span> <span class="pre">playername</span> <span class="pre">=</span> <span class="pre">tweet</span></code>). You may change the <a class="reference internal" href="../Components/Locks.html"><span class="doc">lock</span></a> as you feel is appropriate. Change the overall
permission to <code class="docutils literal notranslate"><span class="pre">Players</span></code> if you want everyone to be able to tweet.</p>
<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">
<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">
<li><p>Auto-Adding the character name to the tweet</p></li>
<li><p>More error-checking of postings</p></li>
<li><p>Changing locks to make tweeting open to more people</p></li>
<li><p>Echo your tweets to an in-game channel</p></li>
</ul>
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">How to connect Evennia to Twitter</a><ul>
<li><a class="reference internal" href="#configuring-twitter">Configuring Twitter</a></li>
<li><a class="reference internal" href="#install-the-twitter-python-module">Install the twitter python module</a></li>
<li><a class="reference internal" href="#a-basic-tweet-command">A basic tweet command</a></li>
<li><a class="reference internal" href="#next-steps">Next Steps</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/How-to-connect-Evennia-to-Twitter.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="How-to-connect-Evennia-to-Twitter.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">How to connect Evennia to Twitter</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

185
docs/1.0-dev/Setup/IRC.html Normal file
View file

@ -0,0 +1,185 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">IRC</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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
Discord</a>, which is mirrored to IRC.</em></p>
<p><a class="reference external" href="http://en.wikipedia.org/wiki/Internet_Relay_Chat">IRC (Internet Relay Chat)</a> is a long standing
chat protocol used by many open-source projects for communicating in real time. By connecting one of
Evennia’s <a class="reference internal" href="../Components/Communications.html"><span class="doc">Channels</span></a> to an IRC channel you can communicate also with people not on
an mud themselves. You can also use IRC if you are only running your Evennia MUD locally on your
computer (your game doesn’t need to be open to the public)! All you need is an internet connection.
For IRC operation you also need <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">
<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="bp">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:
<code class="docutils literal notranslate"><span class="pre">&#64;irc2chan</span></code>. This command is called like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@irc2chan</span><span class="p">[</span><span class="o">/</span><span class="n">switches</span><span class="p">]</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">ircnetwork</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">port</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="c1">#irchannel&gt; &lt;botname&gt;</span>
</pre></div>
</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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> @ccreate irc = This is connected to an irc channel!
</pre></div>
</div>
<p>You will automatically join the new channel.</p>
<p>Next we will create a connection to an external IRC network and channel. There are many, many IRC
nets. <a class="reference external" href="http://www.irchelp.org/irchelp/networks/popular.html">Here is a list</a> of some of the biggest
ones, the one you choose is not really very important unless you want to connect to a particular
channel (also make sure that the network allows for “bots” to connect).</p>
<p>For testing, we choose the <em>Freenode</em> network, <code class="docutils literal notranslate"><span class="pre">irc.freenode.net</span></code>. We will connect to a test
channel, let’s call it <em>#myevennia-test</em> (an IRC channel always begins with <code class="docutils literal notranslate"><span class="pre">#</span></code>). It’s best if you
pick an obscure channel name that didn’t exist previously - if it didn’t exist it will be created
for you.</p>
<blockquote>
<div><p><em>Don’t</em> connect to <code class="docutils literal notranslate"><span class="pre">#evennia</span></code> for testing and debugging, that is Evennia’s official chat channel!
You <em>are</em> welcome to connect your game to <code class="docutils literal notranslate"><span class="pre">#evennia</span></code> once you have everything working though - it
can be a good way to get help and ideas. But if you do, please do so with an in-game channel open
only to your game admins and developers).</p>
</div></blockquote>
<p>The <em>port</em> needed depends on the network. For Freenode this is <code class="docutils literal notranslate"><span class="pre">6667</span></code>.</p>
<p>What will happen is that your Evennia server will connect to this IRC channel as a normal user. This
“user” (or “bot”) needs a name, which you must also supply. Let’s call it “mud-bot”.</p>
<p>To test that the bot connects correctly you also want to log onto this channel with a separate,
third-party IRC client. There are hundreds of such clients available. If you use Firefox, the
<em>Chatzilla</em> plugin is good and easy. Freenode also offers its own web-based chat page. Once you
have connected to a network, the command to join is usually <code class="docutils literal notranslate"><span class="pre">/join</span> <span class="pre">#channelname</span></code> (don’t forget the
#).</p>
<p>Next we connect Evennia with the IRC channel.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@irc2chan</span> <span class="n">irc</span> <span class="o">=</span> <span class="n">irc</span><span class="o">.</span><span class="n">freenode</span><span class="o">.</span><span class="n">net</span> <span class="mi">6667</span> <span class="c1">#myevennia-test mud-bot</span>
</pre></div>
</div>
<p>Evennia will now create a new IRC bot <code class="docutils literal notranslate"><span class="pre">mud-bot</span></code> and connect it to the IRC network and the channel
#myevennia. If you are connected to the IRC channel you will soon see the user <em>mud-bot</em> connect.</p>
<p>Write something in the Evennia channel <em>irc</em>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> irc Hello, World!
[irc] Anna: Hello, World!
</pre></div>
</div>
<p>If you are viewing your IRC channel with a separate IRC client you should see your text appearing
there, spoken by the bot:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>mud-bot&gt; [irc] Anna: Hello, World!
</pre></div>
</div>
<p>Write <code class="docutils literal notranslate"><span class="pre">Hello!</span></code> in your IRC client window and it will appear in your normal channel, marked with the
name of the IRC channel you used (#evennia here).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">irc</span><span class="p">]</span> <span class="n">Anna</span><span class="o">@</span><span class="c1">#myevennia-test: Hello!</span>
</pre></div>
</div>
<p>Your Evennia gamers can now chat with users on external IRC channels!</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">IRC</a><ul>
<li><a class="reference internal" href="#configuring-irc">Configuring IRC</a></li>
<li><a class="reference internal" href="#setting-up-irc-step-by-step">Setting up IRC, step by step</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/IRC.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="IRC.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">IRC</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,236 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing on Android</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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
be able to skip this step. You <em>don’t</em> require a rooted phone to install Evennia though.</p>
<p>Assuming we do not have root, we will install
<a class="reference external" href="https://play.google.com/store/apps/details?id=com.termux&amp;hl=en">Termux</a>.
Termux provides a base installation of Linux essentials, including apt and Python, and makes them
available under a writeable directory. It also gives us a terminal where we can enter commands. By
default, Android doesn’t give you permissions to the root folder, so Termux pretends that its own
installation directory is the root directory.</p>
<p>Termux will set up a base system for us on first launch, but we will need to install some
prerequisites for Evennia. Commands you should run in Termux will look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat file.txt
</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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pkg install -y clang git zlib ndk-sysroot libjpeg-turbo libcrypt python
</pre></div>
</div>
<p>Termux ships with Python 3, perfect. Python 3 has venv (virtualenv) and pip (Python’s module
installer) built-in.</p>
<p>So, let’s set up our virtualenv. This keeps the Python packages we install separate from the system
versions.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd
$ python3 -m venv evenv
</pre></div>
</div>
<p>This will create a new folder, called <code class="docutils literal notranslate"><span class="pre">evenv</span></code>, containing the new python executable.
Next, let’s activate our new virtualenv. Every time you want to work on Evennia, you need to run the
following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ source evenv/bin/activate
</pre></div>
</div>
<p>Your prompt will change to look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>(evenv) $
</pre></div>
</div>
<p>Update the updaters and installers in the venv: pip, setuptools and wheel.</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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">LDFLAGS</span><span class="o">=</span><span class="s2">&quot;-L/data/data/com.termux/files/usr/lib/&quot;</span>
<span class="n">export</span> <span class="n">CFLAGS</span><span class="o">=</span><span class="s2">&quot;-I/data/data/com.termux/files/usr/include/&quot;</span>
</pre></div>
</div>
<p>(these tell clang, the C compiler, where to find the bits for zlib when building Pillow)</p>
<p>Install the latest Evennia in a way that lets you edit the source</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>(evenv) $ pip install --upgrade -e &#39;git+https://github.com/evennia/evennia#egg=evennia&#39;
</pre></div>
</div>
<p>This step will possibly take quite a while - we are downloading Evennia and are then installing it,
building all of the requirements for Evennia to run. If you run into trouble on this step, please
see <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">
<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>
<p>To start a new game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>(evenv) $ evennia --init mygame
(evenv) $ ls
mygame evenv
</pre></div>
</div>
<p>To start the game for the first time:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>(evenv) $ cd mygame
(evenv) $ evennia migrate
(evenv) $ evennia start
</pre></div>
</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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd ~ &amp;&amp; source evenv/bin/activate
(evenv) $ cd mygame
(evenv) $ evennia start
</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">
<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
the command &#64;server in-game will throw an exception. So far, there is no fix for this problem.</p></li>
<li><p>As you might expect, performance is not amazing.</p></li>
<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">
<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>
<ul class="simple">
<li><p>Make sure your packages are up-to-date, try running <code class="docutils literal notranslate"><span class="pre">pkg</span> <span class="pre">update</span> <span class="pre">&amp;&amp;</span> <span class="pre">pkg</span> <span class="pre">upgrade</span> <span class="pre">-y</span></code></p></li>
<li><p>Make sure you’ve installed the clang package. If not, try <code class="docutils literal notranslate"><span class="pre">pkg</span> <span class="pre">install</span> <span class="pre">clang</span> <span class="pre">-y</span></code></p></li>
<li><p>Make sure you’re in the right directory. `cd ~/mygame</p></li>
<li><p>Make sure you’ve sourced your virtualenv. type <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">&amp;&amp;</span> <span class="pre">source</span> <span class="pre">evenv/bin/activate</span></code></p></li>
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installing on Android</a><ul>
<li><a class="reference internal" href="#install-termux">Install Termux</a></li>
<li><a class="reference internal" href="#prerequisites">Prerequisites</a><ul>
<li><a class="reference internal" href="#installing-evennia">Installing Evennia</a></li>
<li><a class="reference internal" href="#final-steps">Final steps</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-evennia">Running Evennia</a></li>
<li><a class="reference internal" href="#caveats">Caveats</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installing-on-Android.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Installing-on-Android.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing on Android</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

609
docs/1.0-dev/Setup/Online-Setup.html Normal file
View file

@ -0,0 +1,609 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Online Setup</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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
(and correctly) block outside access to servers on your machine unless you tell them otherwise.</p>
<p>We will start by showing how to host your server on your own local computer. Even if you plan to
host your “real” game on a remote host later, setting it up locally is useful practice. We cover
remote hosting later in this document.</p>
<p>Out of the box, Evennia uses three ports for outward communication. If your computer has a firewall,
these should be open for in/out communication (and only these, other ports used by Evennia are
internal to your computer only).</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">4000</span></code>, telnet, for traditional mud clients</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">4001</span></code>, HTTP for the website)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">4002</span></code>, websocket, for the web client</p></li>
</ul>
<p>Evennia will by default accept incoming connections on all interfaces (<code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code>) so in principle
anyone knowing the ports to use and has the IP address to your machine should be able to connect to
your game.</p>
<ul class="simple">
<li><p>Make sure Evennia is installed and that you have activated the virtualenv. Start the server with
<code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span> <span class="pre">--log</span></code>. The <code class="docutils literal notranslate"><span class="pre">--log</span></code> (or <code class="docutils literal notranslate"><span class="pre">-l</span></code>) will make sure that the logs are echoed to the
terminal.</p></li>
</ul>
<blockquote>
<div><p>Note: If you need to close the log-view, use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code>. Use just <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--log</span></code> on its own to
start tailing the logs again.</p>
</div></blockquote>
<ul class="simple">
<li><p>Make sure you can connect with your web browser to <code class="docutils literal notranslate"><span class="pre">http://localhost:4001</span></code> or, alternatively,
<code class="docutils literal notranslate"><span class="pre">http:127.0.0.1:4001</span></code> which is the same thing. You should get your Evennia web site and be able to
play the game in the web client. Also check so that you can connect with a mud client to host
<code class="docutils literal notranslate"><span class="pre">localhost</span></code>, port <code class="docutils literal notranslate"><span class="pre">4000</span></code> or host <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>, port <code class="docutils literal notranslate"><span class="pre">4000</span></code>.</p></li>
<li><p><a class="reference external" href="https://www.google.se/search?q=my+ip">Google for “my ip”</a> or use any online service to figure out
what your “outward-facing” IP address is. For our purposes, let’s say your outward-facing IP is
<code class="docutils literal notranslate"><span class="pre">203.0.113.0</span></code>.</p></li>
<li><p>Next try your outward-facing IP by opening <code class="docutils literal notranslate"><span class="pre">http://203.0.113.0:4001</span></code> in a browser. If this works,
that’s it! Also try telnet, with the server set to <code class="docutils literal notranslate"><span class="pre">203.0.113.0</span></code> and port <code class="docutils literal notranslate"><span class="pre">4000</span></code>. However, most
likely it will <em>not</em> work. If so, read on.</p></li>
<li><p>If your computer has a firewall, it may be blocking the ports we need (it may also block telnet
overall). If so, you need to open the outward-facing ports to in/out communication. See the
manual/instructions for your firewall software on how to do this. To test you could also temporarily
turn off your firewall entirely to see if that was indeed the problem.</p></li>
<li><p>Another common problem for not being able to connect is that you are using a hardware router
(like a wifi router). The router sits ‘between’ your computer and the Internet. So the IP you find
with Google is the <em>router’s</em> IP, not that of your computer. To resolve this you need to configure
your router to <em>forward</em> data it gets on its ports to the IP and ports of your computer sitting in
your private network. How to do this depends on the make of your router; you usually configure it
using a normal web browser. In the router interface, look for “Port forwarding” or maybe “Virtual
server”. If that doesn’t work, try to temporarily wire your computer directly to the Internet outlet
(assuming your computer has the ports for it). You’ll need to check for your IP again. If that
works, you know the problem is the router.</p></li>
</ul>
<blockquote>
<div><p>Note: If you need to reconfigure a router, the router’s Internet-facing ports do <em>not</em> have to
have to have the same numbers as your computer’s (and Evennia’s) ports! For example, you might want
to connect Evennia’s outgoing port 4001 to an outgoing router port 80 - this is the port HTTP
requests use and web browsers automatically look for - if you do that you could go to
<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">
<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
<a class="reference external" href="Components/Server-Conf.html#settings-file">settings file</a>. To have Evennia recognize changed port settings you have
to do a full <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reboot</span></code> to also restart the Portal and not just the Server component.</p>
<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>
<span class="n">SERVERNAME</span> <span class="o">=</span> <span class="s2">&quot;MyGame&quot;</span>
<span class="c1"># open to the internet: 4000, 4001, 4002</span>
<span class="c1"># closed to the internet (internal use): 4005, 4006</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="n">WEBSOCKET_CLIENT_PORT</span> <span class="o">=</span> <span class="mi">4002</span>
<span class="n">WEBSERVER_PORTS</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">4001</span><span class="p">,</span> <span class="mi">4005</span><span class="p">)]</span>
<span class="n">AMP_PORT</span> <span class="o">=</span> <span class="mi">4006</span>
<span class="c1"># Optional - security measures limiting interface access</span>
<span class="c1"># (don&#39;t set these before you know things work without them)</span>
<span class="n">TELNET_INTERFACES</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;203.0.113.0&#39;</span><span class="p">]</span>
<span class="n">WEBSOCKET_CLIENT_INTERFACE</span> <span class="o">=</span> <span class="s1">&#39;203.0.113.0&#39;</span>
<span class="n">ALLOWED_HOSTS</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;.mymudgame.com&quot;</span><span class="p">]</span>
<span class="c1"># uncomment if you want to lock the server down for maintenance.</span>
<span class="c1"># LOCKDOWN_MODE = True</span>
</pre></div>
</td></tr></table></div>
<p>Read on for a description of the individual settings.</p>
</div>
<div class="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>
<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>
<span class="c1"># interfaces we should accept. Should be set to your </span>
<span class="c1"># outward-facing IP address(es). Default is ´0.0.0.0´</span>
<span class="c1"># which accepts all interfaces.</span>
<span class="n">TELNET_INTERFACES</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;0.0.0.0&#39;</span><span class="p">]</span>
</pre></div>
</td></tr></table></div>
<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">
<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>
<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>
<span class="c1"># as the only web server on your machine (if available).</span>
<span class="n">WEBSERVER_PORTS</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">4001</span><span class="p">,</span> <span class="mi">4005</span><span class="p">)]</span>
<span class="c1"># Optional for security. Change this to the IP your </span>
<span class="c1"># server can be reached at (normally the same </span>
<span class="c1"># as TELNET_INTERFACES)</span>
<span class="n">WEBSERVER_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 for security. Protects against </span>
<span class="c1"># man-in-the-middle attacks. Change it to your server&#39;s </span>
<span class="c1"># IP address or URL when you run a production server. </span>
<span class="n">ALLOWED_HOSTS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;*&#39;</span><span class="p">]</span>
</pre></div>
</td></tr></table></div>
<p>The web server is always configured with two ports at a time. The <em>outgoing</em> port (<code class="docutils literal notranslate"><span class="pre">4001</span></code> by
default) is the port external connections can use. If you don’t want users to have to specify the
port when they connect, you should set this to <code class="docutils literal notranslate"><span class="pre">80</span></code> - this however only works if you are not running
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">
<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>
<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>
<span class="c1"># your server. The ws:// part is then required. If not given, the client</span>
<span class="c1"># will use its host location. </span>
<span class="n">WEBSOCKET_CLIENT_URL</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
<span class="c1"># Required. Change to a free port for the websocket client to reach</span>
<span class="c1"># the server on. This will be automatically appended </span>
<span class="c1"># to WEBSOCKET_CLIENT_URL by the web client. </span>
<span class="n">WEBSOCKET_CLIENT_PORT</span> <span class="o">=</span> <span class="mi">4002</span>
</pre></div>
</td></tr></table></div>
<p>The websocket-based web client needs to be able to call back to the server, and these settings must
be changed for it to find where to look. If it cannot find the server you will get an warning in
your browser’s Console (in the dev tools of the browser), and the client will revert to the AJAX-
based of the client instead, which tends to be slower.</p>
</div>
<div class="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>
<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>
<span class="n">SSH_PORTS</span> <span class="o">=</span> <span class="p">[</span><span class="mi">4004</span><span class="p">]</span>
<span class="n">SSH_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"># Required private. You should only change this if there is a clash</span>
<span class="c1"># with other services on your host. Should NOT be open to the </span>
<span class="c1"># outside world. </span>
<span class="n">AMP_PORT</span> <span class="o">=</span> <span class="mi">4006</span>
</pre></div>
</td></tr></table></div>
<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">
<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">
<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,
drum up interest for your game and also shows people that Evennia is being used. You can do this
even if you are just starting development - if you don’t give any telnet/web address it will appear
as <em>Not yet public</em> and just be a teaser. If so, pick <em>pre-alpha</em> as the development status.</p>
<p>To register, stand in 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>
</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">
<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
the same benefit. SSL certificates used to cost money on a yearly basis, but there is now a program
that issues them for free with assisted setup to make the entire process less painful.</p>
<p>Options that may be useful in combination with an SSL proxy:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># See above for the section on Lockdown Mode.</span>
<span class="c1"># Useful for a proxy on the public interface connecting to Evennia on localhost.</span>
<span class="n">LOCKDOWN_MODE</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># Have clients communicate via wss after connecting with https to port 4001.</span>
<span class="c1"># Without this, you may get DOMException errors when the browser tries</span>
<span class="c1"># to create an insecure websocket from a secure webpage.</span>
<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">
<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
Encrypt, see these links:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://letsencrypt.org/getting-started/">Let’s Encrypt - Getting Started</a></p></li>
<li><p>The <a class="reference external" href="https://certbot.eff.org/">CertBot Client</a> is a program for automatically obtaining a
certificate, use it and maintain it with your website.</p></li>
</ul>
<p>Also, on Freenode visit the #letsencrypt channel for assistance from the community. For an
additional resource, Let’s Encrypt has a very active <a class="reference external" href="https://community.letsencrypt.org/">community
forum</a>.</p>
<p>[A blog where someone sets up Let’s Encrypt](https://www.digitalocean.com/community/tutorials/how-
to-secure-apache-with-let-s-encrypt-on-ubuntu-16-04)</p>
<p>The only process missing from all of the above documentation is how to pass verification. This is
how Let’s Encrypt verifies that you have control over your domain (not necessarily ownership, it’s
Domain Validation (DV)). This can be done either with configuring a certain path on your web server
or through a TXT record in your DNS. Which one you will want to do is a personal preference, but can
also be based on your hosting choice. In a controlled/cPanel environment, you will most likely have
to use DNS verification.</p>
</div>
</div>
<div class="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">
<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">
<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
extra to have a website.</p>
<p><strong>Advantages</strong></p>
<ul class="simple">
<li><p>Free (except for internet costs and the electrical bill).</p></li>
<li><p>Full control over the server and hardware (it sits right there!).</p></li>
<li><p>Easy to set up.</p></li>
<li><p>Suitable for quick setups - e.g. to briefly show off results to your collaborators.</p></li>
</ul>
<p><strong>Disadvantages</strong></p>
<ul class="simple">
<li><p>You need a good internet connection, ideally without any upload/download limits/costs.</p></li>
<li><p>If you want to run a full game this way, your computer needs to always be on. It could be noisy,
and as mentioned, the electrical bill must be considered.</p></li>
<li><p>No support or safety - if your house burns down, so will your game. Also, you are yourself
responsible for doing regular backups.</p></li>
<li><p>Potentially not as easy if you don’t know how to open ports in your firewall or router.</p></li>
<li><p>Home IP numbers are often dynamically allocated, so for permanent online time you need to set up a
DNS to always re-point to the right place (see below).</p></li>
<li><p>You are personally responsible for any use/misuse of your internet connection– though unlikely
(but not impossible) if running your server somehow causes issues for other customers on the
network, goes against your ISP’s terms of service (many ISPs insist on upselling you to a business-
tier connection) or you are the subject of legal action by a copyright holder, you may find your
main internet connection terminated as a consequence.</p></li>
</ul>
<div class="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>
<p>A complication with using a specific IP address like this is that your home IP might not remain the
same. Many ISPs (Internet Service Providers) allocates a <em>dynamic</em> IP to you which could change at
any time. When that happens, that IP you told people to go to will be worthless. Also, that long
string of numbers is not very pretty, is it? It’s hard to remember and not easy to use in marketing
your game. What you need is to alias it to a more sensible domain name - an alias that follows you
around also when the IP changes.</p>
<ol>
<li><p>To set up a domain name alias, we recommend starting with a free domain name from
<a class="reference external" href="http://freedns.afraid.org/">FreeDNS</a>. Once you register there (it’s free) you have access to tens
of thousands domain names that people have “donated” to allow you to use for your own sub domain.
For example, <code class="docutils literal notranslate"><span class="pre">strangled.net</span></code> is one of those available domains. So tying our IP address to
<code class="docutils literal notranslate"><span class="pre">strangled.net</span></code> using the subdomain <code class="docutils literal notranslate"><span class="pre">evennia</span></code> would mean that one could henceforth direct people to
<code class="docutils literal notranslate"><span class="pre">http://evennia.strangled.net:4001</span></code> for their gaming needs - far easier to remember!</p></li>
<li><p>So how do we make this new, nice domain name follow us also if our IP changes? For this we need
to set up a little program on our computer. It will check whenever our ISP decides to change our IP
and tell FreeDNS that. There are many alternatives to be found from FreeDNS:s homepage, one that
works on multiple platforms is <a class="reference external" href="http://www.inatech.eu/inadyn/">inadyn</a>. Get it from their page or,
in Linux, through something like <code class="docutils literal notranslate"><span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">inadyn</span></code>.</p></li>
<li><p>Next, you login to your account on FreeDNS and go to the
<a class="reference external" href="http://freedns.afraid.org/dynamic/">Dynamic</a> page. You should have a list of your subdomains. Click
the <code class="docutils literal notranslate"><span class="pre">Direct</span> <span class="pre">URL</span></code> link and you’ll get a page with a text message. Ignore that and look at the URL of
the page. It should be ending in a lot of random letters. Everything after the question mark is your
unique “hash”. Copy this string.</p></li>
<li><p>You now start inadyn with the following command (Linux):</p>
<p><code class="docutils literal notranslate"><span class="pre">inadyn</span> <span class="pre">--dyndns_system</span> <span class="pre">default&#64;freedns.afraid.org</span> <span class="pre">-a</span> <span class="pre">&lt;my.domain&gt;,&lt;hash&gt;</span> <span class="pre">&amp;</span></code></p>
</li>
</ol>
<p>where <code class="docutils literal notranslate"><span class="pre">&lt;my.domain&gt;</span></code> would be <code class="docutils literal notranslate"><span class="pre">evennia.strangled.net</span></code> and <code class="docutils literal notranslate"><span class="pre">&lt;hash&gt;</span></code> the string of numbers we copied
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">
<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
scripts” they refer to on their home pages are usually only intended to be CGI-like scripts launched
by their webserver. Even if they allow you shell access (so you can install the Evennia dependencies
in the first place), resource usage will likely be very restricted. Running a full-fledged game
server like Evennia will probably be shunned upon or be outright impossible. If you are unsure,
contact your web hotel and ask about their policy on you running third-party servers that will want
to open custom ports.</p>
<p>The options you probably need to look for are <em>shell account services</em>, <em>VPS:es</em> or <em>Cloud
services</em>. A “Shell account” service means that you get a shell account on a server and can log in
like any normal user. By contrast, a <em>VPS</em> (Virtual Private Server) service usually means that you
get <code class="docutils literal notranslate"><span class="pre">root</span></code> access, but in a virtual machine. There are also <em>Cloud</em>-type services which allows for
starting up multiple virtual machines and pay for what resources you use.</p>
<p><strong>Advantages</strong></p>
<ul class="simple">
<li><p>Shell accounts/VPS/clouds offer more flexibility than your average web hotel - it’s the ability to
log onto a shared computer away from home.</p></li>
<li><p>Usually runs a Linux flavor, making it easy to install Evennia.</p></li>
<li><p>Support. You don’t need to maintain the server hardware. If your house burns down, at least your
game stays online. Many services guarantee a certain level of up-time and also do regular backups
for you. Make sure to check, some offer lower rates in exchange for you yourself being fully
responsible for your data/backups.</p></li>
<li><p>Usually offers a fixed domain name, so no need to mess with IP addresses.</p></li>
<li><p>May have the ability to easily deploy <a class="reference internal" href="Running-Evennia-in-Docker.html"><span class="doc">docker</span></a> versions of evennia
and/or your game.</p></li>
</ul>
<p><strong>Disadvantages</strong></p>
<ul class="simple">
<li><p>Might be pretty expensive (more so than a web hotel). Note that Evennia will normally need at
least 100MB RAM and likely much more for a large production game.</p></li>
<li><p>Linux flavors might feel unfamiliar to users not used to ssh/PuTTy and the Linux command line.</p></li>
<li><p>You are probably sharing the server with many others, so you are not completely in charge. CPU
usage might be limited. Also, if the server people decides to take the server down for maintenance,
you have no choice but to sit it out (but you’ll hopefully be warned ahead of time).</p></li>
</ul>
<div class="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.
Docker images may be a little confusing if you are completely new to them though.</p>
<p>If not using docker, and assuming you know how to connect to your account over ssh/PuTTy, you should
be able to follow the <a class="reference internal" href="Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a> instructions normally. You only need Python
and GIT pre-installed; these should both be available on any servers (if not you should be able to
easily ask for them to be installed). On a VPS or Cloud service you can install them yourself as
needed.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> is not available and you can’t get it, you can download it (it’s just a single file)
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">
<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
[Low End Talk][8] forum can be useful for health checking the many small businesses that offer
“value” hosting, and occasionally for technical suggestions.</p>
<p>There are all sorts of services available. Below are some international suggestions offered by
Evennia users:</p>
<p>Hosting name | Type | Lowest price | Comments
:————–:|:——-:—————
<a class="reference external" href="Setup/http:silvren.com">silvren.com</a> | Shell account | Free for MU* | Private hobby provider so don’t assume backups
or expect immediate support. To ask for an account, connect with a MUD client to iweb.localecho.net,
port 4201 and ask for “Jarin”.
[Digital Ocean][2] | VPS | $5/month | You can get a $50 credit if you use the referral link
https://m.do.co/c/8f64fec2670c - if you do, once you’ve had it long enough to have paid $25 we will
get that as a referral bonus to help Evennia development.
[Amazon Web services][3] | Cloud | ~$5/month / on-demand | Free Tier first 12 months. Regions
available around the globe.
[Amazon Lightsail][9] | Cloud | $5/month | Free first month. AWS’s new “fixed cost” offering.
[Genesis MUD hosting][4] | Shell account | $8/month | Dedicated MUD host with very limited memory
offerings. As for 2017, runs a 13 years old Python version (2.4) so you’d need to either convince
them to update or compile yourself. Note that Evennia needs <em>at least</em> the “Deluxe” package (50MB
RAM) and probably <em>a lot</em> higher for a production game. This host is <em>not</em> recommended for Evennia.
[Host1Plus][5] | VPS &amp; Cloud | $4/month | $4-$8/month depending on length of sign-up period.
[Scaleway][6] | Cloud | €3/month / on-demand | EU based (Paris, Amsterdam). Smallest option
provides 2GB RAM.
[Prgmr][10] | VPS | $5/month | 1 month free with a year prepay. You likely want some experience with
servers with this option as they don’t have a lot of support.
[Linode][11] | Cloud | $5/month / on-demand | Multiple regions. Smallest option provides 1GB RAM
<em>Please help us expand this list.</em></p>
<p><a class="reference external" href="https://www.digitalocean.com/pricing">2</a>
<a class="reference external" href="https://aws.amazon.com/pricing/">3</a>
<a class="reference external" href="http://www.genesismuds.com/">4</a>
<a class="reference external" href="https://www.host1plus.com/">5</a>
<a class="reference external" href="https://www.scaleway.com/">6</a>
<a class="reference external" href="https://lowendbox.com/">7</a>
<a class="reference external" href="https://www.lowendtalk.com">8</a>
<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">
<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
one extra thing you will have to do is update <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> and add
<code class="docutils literal notranslate"><span class="pre">WEBSERVER_PORTS</span> <span class="pre">=</span> <span class="pre">[(8080,</span> <span class="pre">4001)]</span></code>. This will then let you access the web server and do everything
else as normal.</p>
<p>Note that, as of December 2017, Cloud9 was re-released by Amazon as a service within their AWS cloud
service offering. New customers entitled to the 1 year AWS “free tier” may find it provides
sufficient resources to operate a Cloud9 development environment without charge.
https://aws.amazon.com/cloud9/</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Online Setup</a><ul>
<li><a class="reference internal" href="#connecting-from-the-outside">Connecting from the outside</a><ul>
<li><a class="reference internal" href="#settings-example">Settings example</a></li>
<li><a class="reference internal" href="#telnet">Telnet</a></li>
<li><a class="reference internal" href="#web-server">Web server</a></li>
<li><a class="reference internal" href="#web-client">Web client</a></li>
<li><a class="reference internal" href="#other-ports">Other ports</a></li>
<li><a class="reference internal" href="#lockdown-mode">Lockdown mode</a></li>
<li><a class="reference internal" href="#registering-with-the-evennia-game-directory">Registering with the Evennia game directory</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ssl">SSL</a><ul>
<li><a class="reference internal" href="#let-s-encrypt">Let’s Encrypt</a></li>
</ul>
</li>
<li><a class="reference internal" href="#relevant-ssl-proxy-setup-information">Relevant SSL Proxy Setup Information</a></li>
<li><a class="reference internal" href="#hosting-locally-or-remotely">Hosting locally or remotely?</a><ul>
<li><a class="reference internal" href="#using-your-own-computer-as-a-server">Using your own computer as a server</a><ul>
<li><a class="reference internal" href="#setting-up-your-own-machine-as-a-server">Setting up your own machine as a server</a></li>
</ul>
</li>
<li><a class="reference internal" href="#remote-hosting">Remote hosting</a><ul>
<li><a class="reference internal" href="#installing-evennia-on-a-remote-server">Installing Evennia on a remote server</a></li>
</ul>
</li>
<li><a class="reference internal" href="#hosting-options">Hosting options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cloud9">Cloud9</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Online-Setup.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Online-Setup.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Online Setup</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

152
docs/1.0-dev/Setup/RSS.html Normal file
View file

@ -0,0 +1,152 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">RSS</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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
then regularly go online, check this file for updates and let the user know what’s new.</p>
<p>Evennia allows for connecting any number of RSS feeds to any number of in-game channels. Updates to
the feed will be conveniently echoed to the channel. There are many potential uses for this: For
example the MUD might use a separate website to host its forums. Through RSS, the players can then
be notified when new posts are made. Another example is to let everyone know you updated your dev
blog. Admins might also want to track the latest Evennia updates through our own RSS feed
<a class="reference external" href="http://code.google.com/feeds/p/evennia/updates/basic">here</a>.</p>
<div class="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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">feedparser</span>
</pre></div>
</div>
<p>Next you activate RSS support in your config file by settting <code class="docutils literal notranslate"><span class="pre">RSS_ENABLED=True</span></code>.</p>
<p>Start/reload Evennia as a privileged user. You should now have a new command available, <code class="docutils literal notranslate"><span class="pre">&#64;rss2chan</span></code>:</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">
<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!
</pre></div>
</div>
<p>Let’s connect Evennia’s code-update feed to this channel. The RSS url for evennia updates is
<code class="docutils literal notranslate"><span class="pre">https://github.com/evennia/evennia/commits/master.atom</span></code>, so let’s add that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@rss2chan</span> <span class="n">rss</span> <span class="o">=</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">commits</span><span class="o">/</span><span class="n">master</span><span class="o">.</span><span class="n">atom</span>
</pre></div>
</div>
<p>That’s it, really. New Evennia updates will now show up as a one-line title and link in the channel.
Give the <code class="docutils literal notranslate"><span class="pre">&#64;rss2chan</span></code> command on its own to show all connections. To remove a feed from a channel,
you specify the connection again (use the command to see it in the list) but add the <code class="docutils literal notranslate"><span class="pre">/delete</span></code>
switch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="nd">@rss2chan</span><span class="o">/</span><span class="n">delete</span> <span class="n">rss</span> <span class="o">=</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">commits</span><span class="o">/</span><span class="n">master</span><span class="o">.</span><span class="n">atom</span>
</pre></div>
</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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">RSS</a><ul>
<li><a class="reference internal" href="#configuring-rss">Configuring RSS</a><ul>
<li><a class="reference internal" href="#setting-up-rss-step-by-step">Setting up RSS, step by step</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/RSS.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="RSS.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">RSS</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,393 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Running Evennia in Docker</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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
package manager.</p>
<p>To fetch the latest evennia docker image, run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docker</span> <span class="n">pull</span> <span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span>
</pre></div>
</div>
<p>This is a good command to know, it is also how you update to the latest version when we make updates
in the future. This tracks the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch of Evennia.</p>
<blockquote>
<div><p>Note: If you want to experiment with the (unstable) <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch, use <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">pull</span> <span class="pre">evennia/evennia:develop</span></code>.</p>
</div></blockquote>
<p>Next <code class="docutils literal notranslate"><span class="pre">cd</span></code> to a place where your game dir is, or where you want to create it. Then run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game --user
</pre></div>
</div>
<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 $
</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.
If you had anything in the folder you started from, you should see it here (with <code class="docutils literal notranslate"><span class="pre">ls</span></code>) since we
mounted the current directory to <code class="docutils literal notranslate"><span class="pre">usr/src/game</span></code> (with <code class="docutils literal notranslate"><span class="pre">-v</span></code> above). You have the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command
available and can now proceed to create a new game as per the <a class="reference internal" href="Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a>
instructions (you can skip the virtualenv and install ‘globally’ in the container though).</p>
<p>You can run Evennia from inside this container if you want to, it’s like you are root in a little
isolated Linux environment. To exit the container and all processes in there, press <code class="docutils literal notranslate"><span class="pre">Ctrl-D</span></code>. If you
created a new game folder, you will find that it has appeared on-disk.</p>
<blockquote>
<div><p>The game folder or any new files that you created from inside the container will appear as owned
by <code class="docutils literal notranslate"><span class="pre">root</span></code>. If you want to edit the files outside of the container you should change the ownership.
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">
<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
<span class="nv">$UID</span>:<span class="nv">$GID</span> evennia/evennia
</pre></div>
</td></tr></table></div>
<p>This is what it does:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span> <span class="pre">...</span> <span class="pre">evennia/evennia</span></code> tells us that we want to run a new container based on the
<code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> docker image. Everything in between are options for this. The <code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> is
the name of our <a class="reference external" href="https://hub.docker.com/r/evennia/evennia/">official docker image on the dockerhub
repository</a>. If you didn’t do <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">pull</span> <span class="pre">evennia/evennia</span></code> first, the image will be downloaded when running this, otherwise your already
downloaded version will be used. It contains everything needed to run Evennia.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-it</span></code> has to do with creating an interactive session inside the container we start.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--rm</span></code> will make sure to delete the container when it shuts down. This is nice to keep things tidy
on your drive.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-p</span> <span class="pre">4000:4000</span> <span class="pre">-p</span> <span class="pre">4001:4001</span> <span class="pre">-p</span> <span class="pre">4002:4002</span></code> means that we <em>map</em> ports <code class="docutils literal notranslate"><span class="pre">4000</span></code>, <code class="docutils literal notranslate"><span class="pre">4001</span></code> and <code class="docutils literal notranslate"><span class="pre">4002</span></code> from
inside the docker container to same-numbered ports on our host machine. These are ports for telnet,
webserver and websockets. This is what allows your Evennia server to be accessed from outside the
container (such as by your MUD client)!</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-v</span> <span class="pre">$PWD:/usr/src/game</span></code> mounts the current directory (<em>outside</em> the container) to the path
<code class="docutils literal notranslate"><span class="pre">/usr/src/game</span></code> <em>inside</em> the container. This means that when you edit that path in the container you
will actually be modifying the “real” place on your hard drive. If you didn’t do this, any changes
would only exist inside the container and be gone if we create a new one. Note that in linux a
shortcut for the current directory is <code class="docutils literal notranslate"><span class="pre">$PWD</span></code>. If you don’t have this for your OS, you can replace it
with the full path to the current on-disk directory (like <code class="docutils literal notranslate"><span class="pre">C:/Development/evennia/game</span></code> or wherever
you want your evennia files to appear).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--user</span> <span class="pre">$UID:$GID</span></code> ensures the container’s modifications to <code class="docutils literal notranslate"><span class="pre">$PWD</span></code> are done with you user and
group IDs instead of root’s IDs (root is the user running evennia inside the container). This avoids
having stale <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">
<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>
<p>But apart from ease of install, the primary benefit to running an Evennia-based game in a container
is to simplify its deployment into a public production environment. Most cloud-based hosting
providers these days support the ability to run container-based applications. This makes deploying
or updating your game as simple as building a new container image locally, pushing it to your Docker
Hub account, and then pulling from Docker Hub into your AWS/Azure/other docker-enabled hosting
account. The container eliminates the need to install Python, set up a virtualenv, or run pip to
install dependencies.</p>
<div class="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
docker container and pass commands directly to it. The command you pass will be the main process to
run in the container. From your game dir, run for example this command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 --rm -v $PWD:/usr/src/game
</pre></div>
</div>
<p>evennia/evennia evennia start -l</p>
<p>This will start Evennia as the foreground process, echoing the log to the terminal. Closing the
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">
<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
into it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FROM</span> <span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="p">:</span><span class="n">latest</span>
<span class="n">ENTRYPOINT</span> <span class="n">evennia</span> <span class="n">start</span> <span class="o">-</span><span class="n">l</span>
</pre></div>
</div>
<p>These are instructions for building a new docker image. This one is based on the official
<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 .
</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
<code class="docutils literal notranslate"><span class="pre">mydhaccount</span></code> is the name of your <code class="docutils literal notranslate"><span class="pre">dockerhub</span></code> account. If you don’t have a dockerhub account you can
build the image locally only (name the container whatever you like in that case, like just
<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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>docker run -it --rm -p 4000:4000 -p 4001:4001 -p 4002:4002 -v $PWD:/usr/src/game --user $UID:$GID
mydhaccount/mygame
</pre></div>
</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">
<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
folder there, the internal one will be used. So for deploying evennia on a server, omit the <code class="docutils literal notranslate"><span class="pre">-v</span></code>
option and just give the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>docker run -it --rm -d -p 4000:4000 -p 4001:4001 -p 4002:4002 --user $UID:$GID mydhaccount/mygame
</pre></div>
</div>
<p>Your game will be downloaded from your docker-hub account and a new container will be built using
the image and started on the server! If your server environment forces you to use different ports,
you can just map the normal ports differently in the command above.</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
CONTAINER ID IMAGE COMMAND CREATED ...
f6d4ca9b2b22 mygame <span class="s2">&quot;/bin/sh -c &#39;evenn...&quot;</span> About a minute ago ...
</pre></div>
</td></tr></table></div>
<p>Note the container ID, this is how you manage the container as it runs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">docker</span> <span class="n">logs</span> <span class="n">f6d4ca9b2b22</span>
</pre></div>
</div>
<p>Looks at the STDOUT output of the container (i.e. the normal server log)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">docker</span> <span class="n">logs</span> <span class="o">-</span><span class="n">f</span> <span class="n">f6d4ca9b2b22</span>
</pre></div>
</div>
<p>Tail the log (so it updates to your screen ‘live’).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">docker</span> <span class="n">pause</span> <span class="n">f6d4ca9b2b22</span>
</pre></div>
</div>
<p>Suspend the state of the container.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">docker</span> <span class="n">unpause</span> <span class="n">f6d4ca9b2b22</span>
</pre></div>
</div>
<p>Un-suspend it again after a pause. It will pick up exactly where it were.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">docker</span> <span class="n">stop</span> <span class="n">f6d4ca9b2b22</span>
</pre></div>
</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">
<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
<code class="docutils literal notranslate"><span class="pre">ONBUILD</span></code> directive handles setting up a volume and copying your game directory code into the proper
location within the container.</p>
<p>In most cases, the Dockerfile for an Evennia-based game will only need the <code class="docutils literal notranslate"><span class="pre">FROM</span> <span class="pre">evennia/evennia:latest</span></code> directive, and optionally a <code class="docutils literal notranslate"><span class="pre">MAINTAINER</span></code> directive if you plan to publish
your image on Docker Hub and would like to provide contact info.</p>
<p>For more information on Dockerfile directives, see the <a class="reference external" href="https://docs.docker.com/engine/reference/builder/">Dockerfile
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">
<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
arbitrary commit.</p>
<ol class="simple">
<li><p>Use git tools to checkout the commit that you want to base your image upon. (In the example
below, we’re checking out commit a8oc3d5b.)</p></li>
</ol>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">my</span><span class="o">-</span><span class="n">stable</span><span class="o">-</span><span class="n">branch</span> <span class="n">a8oc3d5b</span>
</pre></div>
</div>
<ol class="simple">
<li><p>Change your working directory to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory containing <code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code>. Note that
<code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code> has changed over time, so if you are going far back in the commit history you might
want to bring a copy of the latest <code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code> with you and use that instead of whatever version
was used at the time.</p></li>
<li><p>Use the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">build</span></code> command to build the image based off of the currently checked out commit.
The example below assumes your docker account is <strong>mydhaccount</strong>.</p></li>
</ol>
<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">mydhaccount</span><span class="o">/</span><span class="n">evennia</span> <span class="o">.</span>
</pre></div>
</div>
<ol class="simple">
<li><p>Now you have a base evennia docker image built off of a specific commit. To use this image to
build your game, you would modify <strong>FROM</strong> directive in the <strong>Dockerfile</strong> for your game directory
to be:</p></li>
</ol>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FROM</span> <span class="n">mydhacct</span><span class="o">/</span><span class="n">evennia</span><span class="p">:</span><span class="n">latest</span>
</pre></div>
</div>
<p>Note: From this point, you can also use the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">tag</span></code> command to set a specific tag on your image
and/or upload it into Docker Hub under your account.</p>
<ol class="simple">
<li><p>At this point, build your game using the same <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">build</span></code> command as usual. Change your
working directory to be your game directory and run</p></li>
</ol>
<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">
<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
specified every time we run our container. A sample <code class="docutils literal notranslate"><span class="pre">docker-compose.yml</span></code> file to run a containerized
Evennia game in development might look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">version</span><span class="p">:</span> <span class="s1">&#39;2&#39;</span>
<span class="n">services</span><span class="p">:</span>
<span class="n">evennia</span><span class="p">:</span>
<span class="n">image</span><span class="p">:</span> <span class="n">mydhacct</span><span class="o">/</span><span class="n">mygame</span>
<span class="n">stdin_open</span><span class="p">:</span> <span class="n">true</span>
<span class="n">tty</span><span class="p">:</span> <span class="n">true</span>
<span class="n">ports</span><span class="p">:</span>
<span class="o">-</span> <span class="s2">&quot;4001-4002:4001-4002&quot;</span>
<span class="o">-</span> <span class="s2">&quot;4000:4000&quot;</span>
<span class="n">volumes</span><span class="p">:</span>
<span class="o">-</span> <span class="o">.</span><span class="p">:</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">src</span><span class="o">/</span><span class="n">game</span>
</pre></div>
</div>
<p>With this file in the game directory next to the <code class="docutils literal notranslate"><span class="pre">Dockerfile</span></code>, starting the container is as simple
as</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docker</span><span class="o">-</span><span class="n">compose</span> <span class="n">up</span>
</pre></div>
</div>
<p>For more information about <code class="docutils literal notranslate"><span class="pre">docker-compose</span></code>, see <a class="reference external" href="https://docs.docker.com/compose/gettingstarted/">Getting Started with docker-
compose</a>.</p>
<blockquote>
<div><p>Note that with this setup you lose the <code class="docutils literal notranslate"><span class="pre">--user</span> <span class="pre">$UID</span></code> option. The problem is that the variable
<code class="docutils literal notranslate"><span class="pre">UID</span></code> is not available inside the configuration file <code class="docutils literal notranslate"><span class="pre">docker-compose.yml</span></code>. A workaround is to
hardcode your user and group id. In a terminal run <code class="docutils literal notranslate"><span class="pre">echo</span>&#160; <span class="pre">$UID:$GID</span></code> and if for example you get
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Running Evennia in Docker</a><ul>
<li><a class="reference internal" href="#install-evennia-through-docker">Install Evennia through docker</a><ul>
<li><a class="reference internal" href="#description-of-the-docker-run-command">Description of the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span></code> command</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-your-game-as-a-docker-image">Running your game as a docker image</a><ul>
<li><a class="reference internal" href="#start-evennia-and-run-through-docker">Start Evennia and run through docker</a></li>
<li><a class="reference internal" href="#create-your-own-game-image">Create your own game image</a></li>
<li><a class="reference internal" href="#run-container-from-your-game-image-for-development">Run container from your game image for development</a></li>
<li><a class="reference internal" href="#deploy-game-image-for-production">Deploy game image for production</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-it-works">How it Works</a><ul>
<li><a class="reference internal" href="#what-if-i-don-t-want-latest">What if I Don’t Want “LATEST”?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#additional-creature-comforts">Additional Creature Comforts</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Running-Evennia-in-Docker.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Running-Evennia-in-Docker.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Running Evennia in Docker</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

264
docs/1.0-dev/Setup/Security.html Normal file
View file

@ -0,0 +1,264 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Security</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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
vulnerable systems they can break into. Who owns the system is irrelevant– it doesn’t matter if it
belongs to you or the Pentagon, the goal is to take advantage of poorly-secured systems and see what
resources can be controlled or stolen from them.</p>
<p>If you’re considering deploying to a cloud-based host, you have a vested interest in securing your
applications– you likely have a credit card on file that your host can freely bill. Hackers pegging
your CPU to mine cryptocurrency or saturating your network connection to participate in a botnet or
send spam can run up your hosting bill, get your service suspended or get your address/site
blacklisted by ISPs. It can be a difficult legal or political battle to undo this damage after the
fact.</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">
<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>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">http_requests.log</span></code> will show you what HTTP requests have been made against Evennia’s built-in
webserver (TwistedWeb). This is a good way to see if people are innocuously browsing your site or
trying to break it through code injection.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">portal.log</span></code> will show you various networking-related information. This is a good place to check
for odd or unusual types or amounts of connections to your game, or other networking-related
issues– like when users are reporting an inability to connect.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">server.log</span></code> is the MUX administrator’s best friend. Here is where you’ll find information
pertaining to who’s trying to break into your system by guessing at passwords, who created what
objects, and more. If your game fails to start or crashes and you can’t tell why, this is the first
place you should look for answers. Security-related events are prefixed with an <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">
<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
production– leaving them on can expose variables or code someone with malicious intent can easily
abuse to compromise your environment.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">server/conf/settings.py</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Disable Django&#39;s debug mode</span>
<span class="n">DEBUG</span> <span class="o">=</span> <span class="kc">False</span>
<span class="c1"># Disable the in-game equivalent</span>
<span class="n">IN_GAME_ERRORS</span> <span class="o">=</span> <span class="kc">False</span>
<span class="c1"># If you&#39;ve registered a domain name, force Django to check host headers. Otherwise leave this</span>
</pre></div>
</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">
<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
or zip archive), but <a class="reference external" href="https://insinuator.net/2014/05/django-image-validation-vulnerability/">code can be injected into an image
file</a> <em>after</em> the headers
that can be interpreted as HTML and/or give an attacker a web shell through which they can access
other filesystem resources.</p>
<p><a class="reference external" href="https://docs.djangoproject.com/en/dev/topics/security/#user-uploaded-content-security">Django has a more comprehensive overview of how to handle user-uploaded
files</a>, but
in short you should take care to do one of two things–</p>
<ul class="simple">
<li><p>Serve all user-uploaded assets from a <em>separate</em> domain or CDN (<em>not</em> a subdomain of the one you
already have!). For example, you may be browsing <code class="docutils literal notranslate"><span class="pre">reddit.com</span></code> but note that all the user-submitted
images are being served from the <code class="docutils literal notranslate"><span class="pre">redd.it</span></code> domain. There are both security and performance benefits
to this (webservers tend to load local resources one-by-one, whereas they will request external
resources in bulk).</p></li>
<li><p>If you don’t want to pay for a second domain, don’t understand what any of this means or can’t be
bothered with additional infrastructure, then simply reprocess user images upon receipt using an
image library. Convert them to a different format, for example. <em>Destroy the originals!</em></p></li>
</ul>
</div>
<div class="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
an attacker can attempt to validate stolen lists of credentials to see which ones might be shared by
your users. Django’s security is robust, but if you don’t want/need these features and fully intend
to force your users to use traditional clients to access your game, you might consider disabling
either/both to minimize your attack surface.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">server/conf/settings.py</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Disable the Javascript webclient</span>
<span class="n">WEBCLIENT_ENABLED</span> <span class="o">=</span> <span class="kc">False</span>
<span class="c1"># Disable the website altogether</span>
<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">
<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,
many public wifi hotspots block ssh traffic over port 22 so you might not be able to access your
server from these locations if you like to work remotely or don’t have a home internet connection.</p>
<p>If you don’t intend on running a website or securing it with TLS, you can mitigate both problems by
changing the port used for ssh to 443, which most/all hotspot providers assume is HTTPS traffic and
allows through.</p>
<p>(Ubuntu) In /etc/ssh/sshd_config, change the following variable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># What ports, IPs and protocols we listen for</span>
<span class="n">Port</span> <span class="mi">443</span>
</pre></div>
</div>
<p>Save, close, then run the following command:</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">
<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>
<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">ufw</span>
</pre></div>
</div>
<p>UFW’s default policy is to deny everything. We must specify what we want to allow through our
firewall.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Allow terminal connections to your game</span>
<span class="n">sudo</span> <span class="n">ufw</span> <span class="n">allow</span> <span class="mi">4000</span><span class="o">/</span><span class="n">tcp</span>
<span class="c1"># Allow browser connections to your website</span>
<span class="n">sudo</span> <span class="n">ufw</span> <span class="n">allow</span> <span class="mi">4001</span><span class="o">/</span><span class="n">tcp</span>
</pre></div>
</div>
<p>Use ONE of the next two commands depending on which port your ssh daemon is listening on:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">ufw</span> <span class="n">allow</span> <span class="mi">22</span><span class="o">/</span><span class="n">tcp</span>
<span class="n">sudo</span> <span class="n">ufw</span> <span class="n">allow</span> <span class="mi">443</span><span class="o">/</span><span class="n">tcp</span>
</pre></div>
</div>
<p>Finally:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">ufw</span> <span class="n">enable</span>
</pre></div>
</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">
<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>
<p>For example, Evennia’s game engine and webservice are tightly integrated. If you bring your game
down for maintenance (or if it simply crashes) your website will go down with it. In these cases a
standalone webserver can still be used to display a maintenance page or otherwise communicate to
your users the reason for the downtime, instead of disappearing off the face of the earth and
returning opaque <code class="docutils literal notranslate"><span class="pre">SERVER</span> <span class="pre">NOT</span> <span class="pre">FOUND</span></code> error messages.</p>
<p>Proper webservers are also written in more efficient programming languages than Python, and while
Twisted can handle its own, putting a webserver in front of it is like hiring a bouncer to deal with
nuisances and crowds before they even get in the door.</p>
<p>Many of the popular webservers also let you plug in additional modules (like
<a class="reference external" href="https://en.wikipedia.org/wiki/ModSecurity">mod_security</a> for Apache) that can be used to detect
(and block!) malicious users or requests before they even touch your game or site. There are also
automated solutions for installing and configuring TLS (via <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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Security</a><ul>
<li><a class="reference internal" href="#know-your-logs">Know your logs</a></li>
<li><a class="reference internal" href="#disable-development-debugging-options">Disable development/debugging options</a></li>
<li><a class="reference internal" href="#handle-user-uploaded-images-with-care">Handle user-uploaded images with care</a></li>
<li><a class="reference internal" href="#disable-the-web-interface">Disable the web interface</a></li>
<li><a class="reference internal" href="#change-your-ssh-port">Change your ssh port</a></li>
<li><a class="reference internal" href="#set-up-a-firewall">Set up a firewall</a></li>
<li><a class="reference internal" href="#use-an-external-webserver">Use an external webserver</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Security.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Security.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Security</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,99 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">The Evennia Default Settings file</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Settings-File.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Settings-File.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">The Evennia Default Settings file</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

151
docs/1.0-dev/Setup/Setup-Overview.html Normal file
View file

@ -0,0 +1,151 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Server Setup and Life</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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>
<li><p><a class="reference internal" href="Extended-Installation.html"><span class="doc">Extended Install instructions</span></a> - if you have trouble or want to contribute to Evennia itself</p></li>
<li><p><a class="reference internal" href="Running-Evennia-in-Docker.html"><span class="doc">Running through Docker</span></a> - alternative install method, useful for quick deployment on remote servers</p></li>
<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">
<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">
<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>
<li><p><a class="reference internal" href="Choosing-An-SQL-Server.html"><span class="doc">Change database engine</span></a> - if you want to use something other than SQLite3</p></li>
<li><p><a class="reference internal" href="Evennia-Game-Index.html"><span class="doc">Evennia game index</span></a> - register your upcoming game with the index to start the hype going</p></li>
<li><p><a class="reference internal" href="IRC.html"><span class="doc">Chat on IRC</span></a> - how to link your game’s channels to an external <a class="reference external" href="https://en.wikipedia.org/wiki/Internet_Relay_Chat">IRC</a> channel</p></li>
<li><p><a class="reference internal" href="Grapevine.html"><span class="doc">Chat on Grapevine</span></a> - how to link your game’s channels the <a class="reference external" href="https://grapevine.haus/">Grapevine</a> mud network/chat</p></li>
<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">
<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>
<ul>
<li><p><a class="reference internal" href="HAProxy-Config.html"><span class="doc">Using HAProxy</span></a> - putting a proxy in front of the game server for security</p></li>
<li><p><a class="reference internal" href="Apache-Config.html"><span class="doc">Using Apache as a webserver</span></a> - use Apache instead of Evennia’s webserver (limited support)</p></li>
</ul>
</li>
<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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Server Setup and Life</a><ul>
<li><a class="reference internal" href="#installation-running">Installation &amp; running</a></li>
<li><a class="reference internal" href="#installing-custom-game-dirs">Installing custom game dirs</a></li>
<li><a class="reference internal" href="#configuring">Configuring</a></li>
<li><a class="reference internal" href="#going-public">Going public</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Setup-Overview.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Setup-Overview.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Server Setup and Life</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

193
docs/1.0-dev/Setup/Setup-Quickstart.html Normal file
View file

@ -0,0 +1,193 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Setup quickstart</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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">
<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
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">evennia</span>
</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
systems.</p>
</div>
<div class="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
name your game whatever you like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">init</span> <span class="n">mygame</span>
</pre></div>
</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">
<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>
</pre></div>
</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>
</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>
<p>If all went well, the server is now up and running. Point a legacy MUD/telnet client to <code class="docutils literal notranslate"><span class="pre">localhost:4000</span></code> or
a web browser at <a class="reference external" href="http://localhost:4001">http://localhost:4001</a> to play your new (if empty) game!</p>
<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">
<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>
</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>
</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">
<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>
</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>
</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">
<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/Starting-Part1.html"><span class="doc">Starting Tutorial</span></a> to learn how to start making your new game!</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Setup quickstart</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#initialize-a-new-game">Initialize a new game</a></li>
<li><a class="reference internal" href="#start-the-new-game">Start the new game</a></li>
<li><a class="reference internal" href="#see-server-logs">See server logs</a></li>
<li><a class="reference internal" href="#restarting-and-stopping">Restarting and stopping</a></li>
<li><a class="reference internal" href="#the-next-step">The Next step</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Setup-Quickstart.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Setup-Quickstart.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Setup quickstart</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>

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

@ -0,0 +1,303 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="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
Evennia as described in the <a class="reference internal" href="Setup-Quickstart.html"><span class="doc">Setup Quickstart</span></a> page.</p>
<blockquote>
<div><p>Hint: If you ever try the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command and get an error complaining that the command is not
available, make sure your <a class="reference external" href="Glossary.html#virtualenv">virtualenv</a> is active.</p>
</div></blockquote>
<p>Below are described the various management options. Run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">-</span><span class="n">h</span>
</pre></div>
</div>
<p>to give you a brief help and</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">menu</span>
</pre></div>
</div>
<p>to give you a menu with options.</p>
<div class="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
exactly how players connect, only that they have. The <em>Portal</em> is a gateway to which players
connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the
game. Both are required for a functioning mud.</p>
<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>The above command will start the Portal, which in turn will boot up the Server. The command will
print a summary of the process and unless there is an error you will see no further output. Both
components will instead log to log files in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>. For convenience you can follow
those logs directly in your terminal by attaching <code class="docutils literal notranslate"><span class="pre">-l</span></code> to commands:</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>
</pre></div>
</div>
<p>Will start following the logs of an already running server. When starting Evennia you can also do</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>
</pre></div>
</div>
<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">
<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
directly to the terminal (rather than to log files that we then echo to the terminal) and you can
kill the process (not just the log-file view) with <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">istart</span>
</pre></div>
</div>
<p>will start/restart the <em>Server</em> in interactive mode. This is required if you want to run a
<em>debugger</em>. Next time you reload the server, it will return to normal mode.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">ipstart</span>
</pre></div>
</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">
<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
server
reboots. Since they are connected to the <em>Portal</em>, their connections are not lost.</p>
<p>Reloading is as close to a “warm reboot” you can get. It reinitializes all code of Evennia, but
doesn’t kill “persistent” <a class="reference internal" href="../Components/Scripts.html"><span class="doc">Scripts</span></a>. It also calls <code class="docutils literal notranslate"><span class="pre">at_server_reload()</span></code> hooks on all
objects so you
can save eventual temporary properties you want.</p>
<p>From in-game the <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> command is used. You can also reload the server from outside the game:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">reload</span>
</pre></div>
</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">
<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
will be disconnected during a
reset. A reset will however purge all non-persistent scripts and will call <code class="docutils literal notranslate"><span class="pre">at_server_shutdown()</span></code>
hooks. It can be a good way to clean unsafe scripts during development, for example.</p>
<p>From in-game the <code class="docutils literal notranslate"><span class="pre">&#64;reset</span></code> command is used. From the terminal:</p>
<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">
<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>
<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>This is identical to doing these two commands:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span> <span class="n">stop</span>
<span class="n">evennia</span> <span class="n">start</span>
</pre></div>
</div>
</div>
<div class="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>
<p>From inside the game you initiate a shutdown with the <code class="docutils literal notranslate"><span class="pre">&#64;shutdown</span></code> command. From command line you do</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>
<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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">info</span>
</pre></div>
</div>
<p>You can also get a briefer run-status from both components with this command</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">status</span>
</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">
<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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">skill</span>
</pre></div>
</div>
<p>To kill both Server and Portal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">kill</span>
</pre></div>
</div>
<p>Note that this functionality is not supported on Windows.</p>
</div>
<div class="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>
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">
<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
related to Evennia:</p>
<ul class="simple">
<li><p>1 x <code class="docutils literal notranslate"><span class="pre">twistd</span> <span class="pre">...</span> <span class="pre">evennia/server/portal/portal.py</span></code> - this is the Portal process.</p></li>
<li><p>3 x <code class="docutils literal notranslate"><span class="pre">twistd</span> <span class="pre">...</span> <span class="pre">server.py</span></code> - One of these processes manages Evennia’s Server component, the main
game. The other processes (with the same name but different process id) handle’s Evennia’s
internal web server threads. You can look at <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">
<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
just have you see a traceback in the game, in the log or on the command line. For some really
serious syntax errors though, your module might not even be recognized as valid Python. Evennia may
then fail to restart correctly.</p>
<p>From inside the game you see a text about the Server restarting followed by an ever growing list of
“…”. Usually this only lasts a very short time (up to a few seconds). If it seems to go on, it
means the Portal is still running (you are still connected to the game) but the Server-component of
Evennia failed to restart (that is, it remains in a shut-down state). Look at your log files or
terminal to see what the problem is - you will usually see a clear traceback showing what went
wrong.</p>
<p>Fix your bug then run</p>
<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>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>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Start Stop Reload</a><ul>
<li><a class="reference internal" href="#starting-evennia">Starting Evennia</a></li>
<li><a class="reference internal" href="#foreground-mode">Foreground mode</a></li>
<li><a class="reference internal" href="#reloading">Reloading</a></li>
<li><a class="reference internal" href="#resetting">Resetting</a></li>
<li><a class="reference internal" href="#rebooting">Rebooting</a></li>
<li><a class="reference internal" href="#shutting-down">Shutting down</a></li>
<li><a class="reference internal" href="#status-and-info">Status and info</a></li>
<li><a class="reference internal" href="#killing-linux-mac-only">Killing (Linux/Mac only)</a></li>
<li><a class="reference internal" href="#django-options">Django options</a></li>
<li><a class="reference internal" href="#advanced-handling-of-evennia-processes">Advanced handling of Evennia processes</a><ul>
<li><a class="reference internal" href="#syntax-errors-during-live-development">Syntax errors during live development</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Start-Stop-Reload.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Start-Stop-Reload.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.1/index.html">0.9.1 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.1.
</div>
</body>
</html>