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

Revert "Updated HTML docs."

Browse source 
This reverts commit 51d5840b8b.
This commit is contained in:
Griatch 2022-11-14 22:43:45 +01:00
parent 51d5840b8b
commit e34f258a92
2504 changed files with 820160 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -0,0 +1,332 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Apache Config &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Tutorials and Howto’s" href="../Howtos/Howtos-Overview.html" />
<link rel="prev" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together" href="HAProxy-Config.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="right" >
<a href="../Howtos/Howtos-Overview.html" title="Tutorials and Howto’s"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="HAProxy-Config.html" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="HAProxy-Config.html"
title="previous chapter">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../Howtos/Howtos-Overview.html"
title="next chapter">Tutorials and Howto’s</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Apache-Config.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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>
<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>
<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>
</section>
<section id="copy-and-modify-the-vhost">
<h3>Copy and modify the VHOST<a class="headerlink" href="#copy-and-modify-the-vhost" title="Permalink to this headline"></a></h3>
<p>After <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is installed, copy the <code class="docutils literal notranslate"><span class="pre">evennia/web/utils/evennia_wsgi_apache.conf</span></code> file to your
apache2 vhosts/sites folder. On Debian/Ubuntu, this is <code class="docutils literal notranslate"><span class="pre">/etc/apache2/sites-enabled/</span></code>. Make your
modifications <strong>after</strong> copying the file there.</p>
<p>Read the comments and change the paths to point to the appropriate locations within your setup.</p>
</section>
<section id="restart-reload-apache">
<h3>Restart/Reload Apache<a class="headerlink" href="#restart-reload-apache" title="Permalink to this headline"></a></h3>
<p>You’ll then want to reload or restart apache2 after changing the configurations.</p>
<ul>
<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>
</section>
<section id="enjoy">
<h3>Enjoy<a class="headerlink" href="#enjoy" title="Permalink to this headline"></a></h3>
<p>With any luck, you’ll be able to point your browser at your domain or subdomain that you set up in
your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error
message and work from there. Questions may be directed to our <a class="reference external" href="https://evennia.com">Evennia Community
site</a>.</p>
</section>
<section id="a-note-on-code-reloading">
<h3>A note on code reloading<a class="headerlink" href="#a-note-on-code-reloading" title="Permalink to this headline"></a></h3>
<p>If your <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is set up to run on daemon mode (as will be the case by default on Debian and
Ubuntu), you may tell <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> to reload by using the <code class="docutils literal notranslate"><span class="pre">touch</span></code> command on
<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>
</section>
<section id="further-notes-and-hints">
<h3>Further notes and hints:<a class="headerlink" href="#further-notes-and-hints" title="Permalink to this headline"></a></h3>
<p>If you get strange (and usually uninformative) <code class="docutils literal notranslate"><span class="pre">Permission</span> <span class="pre">denied</span></code> errors from Apache, make sure
that your <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory is located in a place the webserver may actually access. For example,
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-none notranslate"><div class="highlight"><pre><span></span>&lt;Directory &quot;/home/&lt;yourname&gt;/evennia/game/web&quot;&gt;
Options +ExecCGI
Allow from all
&lt;/Directory&gt;
</pre></div>
</div>
</section>
</section>
<section id="mod-proxy-and-mod-ssl-setup">
<h2><code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> setup<a class="headerlink" href="#mod-proxy-and-mod-ssl-setup" title="Permalink to this headline"></a></h2>
<p>Below are steps on running Evennia using a front-end proxy (Apache HTTP), <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code>,
<code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code>, and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code>. <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code> will simply be
referred to as
<code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> below.</p>
<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>
</section>
<section id="tls-proxy-websocket-configuration">
<h3>TLS proxy+websocket configuration<a class="headerlink" href="#tls-proxy-websocket-configuration" title="Permalink to this headline"></a></h3>
<p>Below is a sample configuration for Evennia with a TLS-enabled http and websocket proxy.</p>
<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>
</section>
<section id="evennia-secure-websocket-configuration">
<h4>Evennia secure websocket configuration<a class="headerlink" href="#evennia-secure-websocket-configuration" title="Permalink to this headline"></a></h4>
<p>There is a slight trick in setting up Evennia so websocket traffic is handled correctly by the
proxy. You must set the <code class="docutils literal notranslate"><span class="pre">WEBSOCKET_CLIENT_URL</span></code> setting in your <code class="docutils literal notranslate"><span class="pre">mymud/server/conf/settings.py</span></code> file:</p>
<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>
</section>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="../Howtos/Howtos-Overview.html" title="Tutorials and Howto’s"
>next</a> |</li>
<li class="right" >
<a href="HAProxy-Config.html" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,457 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Choosing An SQL Server &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Evennia Game Index" href="Evennia-Game-Index.html" />
<link rel="prev" title="Evennia Default settings file" href="Settings-Default.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="right" >
<a href="Evennia-Game-Index.html" title="Evennia Game Index"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Settings-Default.html" title="Evennia Default settings file"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Choosing An SQL Server</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<li><a class="reference internal" href="#advanced-postgresql-usage-remote-server">Advanced Postgresql Usage (Remote Server)</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>
<h4>Previous topic</h4>
<p class="topless"><a href="Settings-Default.html"
title="previous chapter">Evennia Default settings file</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Evennia-Game-Index.html"
title="next chapter">Evennia Game Index</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Choosing-An-SQL-Server.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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="https://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="https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases">Notes about supported
Databases</a> page.</p>
<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>
<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-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</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"><div class="highlight"><pre><span></span> sqlite3 server/evennia.db3
<span class="c1"># or</span>
evennia dbshell
</pre></div>
</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>
</section>
</section>
<section id="postgresql">
<h2>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.postgresql.org/">PostgreSQL</a> is an open-source database engine, recommended by Django.
While not as fast as SQLite for normal usage, it will scale better than SQLite, especially if your
game has an very large database and/or extensive web presence through a separate server process.</p>
<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"><div class="highlight"><pre><span></span> psql -U postgres --password
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>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>
<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"><div class="highlight"><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">&#39;somepassword&#39;</span><span class="p">;</span><span class="w"></span>
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span><span class="w"></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="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">client_encoding</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">&#39;utf8&#39;</span><span class="p">;</span><span class="w"></span>
<span class="k">ALTER</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">default_transaction_isolation</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">&#39;read committed&#39;</span><span class="p">;</span><span class="w"></span>
<span class="k">ALTER</span><span class="w"> </span><span class="k">ROLE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">timezone</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="s1">&#39;UTC&#39;</span><span class="p">;</span><span class="w"></span>
<span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="w"> </span><span class="k">TO</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span><span class="w"></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>
</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>
</section>
<section id="evennia-postgresql-configuration">
<h3>Evennia PostgreSQL configuration<a class="headerlink" href="#evennia-postgresql-configuration" title="Permalink to this headline"></a></h3>
<p>Edit `mygame/server/conf/secret_settings.py and add the following section:</p>
<div class="highlight-python notranslate"><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>
</div>
<p>If you used some other name for the database and user, enter those instead. Run</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</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-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
</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>
</section>
<section id="advanced-postgresql-usage-remote-server">
<h3>Advanced Postgresql Usage (Remote Server)<a class="headerlink" href="#advanced-postgresql-usage-remote-server" title="Permalink to this headline"></a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The example below is for a server within a private network that is not open to
the Internet. Be sure to understand the details before making any changes to
an Internet-accessible server.</p>
</div>
<p>The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.</p>
<p>Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions <a class="reference internal" href="#install-and-initial-setup-of-postgresql"><span class="std std-doc">above</span></a> on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.</p>
<p>First, determine which cluster is running your database. Use <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
<span class="m">12</span> main <span class="m">5432</span> online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
</pre></div>
</div>
<p>Next, edit the database’s <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>. This is found on Ubuntu systems
in <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/&lt;ver&gt;/&lt;cluster&gt;</span></code>, where <code class="docutils literal notranslate"><span class="pre">&lt;ver&gt;</span></code> and <code class="docutils literal notranslate"><span class="pre">&lt;cluster&gt;</span></code> are
what are reported in the <code class="docutils literal notranslate"><span class="pre">pg_lscluster</span></code> output. So, for the above example,
the file is <code class="docutils literal notranslate"><span class="pre">/etc/postgresql/12/main/postgresql.conf</span></code>.</p>
<p>In this file, look for the line with <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code>. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">listen_address</span> <span class="o">=</span> <span class="s1">&#39;localhost&#39;</span> <span class="c1"># What IP address(es) to listen on;</span>
<span class="c1"># comma-separated list of addresses;</span>
<span class="c1"># defaults to &#39;localhost&#39;; use &#39;*&#39; for all</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Misconfiguring the wrong cluster may cause problems
with existing clusters.</p>
</div>
<p>Also, note the line with <code class="docutils literal notranslate"><span class="pre">port</span> <span class="pre">=</span></code> and keep the port number in mind.</p>
<p>Set <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code> to <code class="docutils literal notranslate"><span class="pre">'*'</span></code>. This permits postgresql to accept connections
on any interface.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Setting <code class="docutils literal notranslate"><span class="pre">listen_addresses</span></code> to <code class="docutils literal notranslate"><span class="pre">'*'</span></code> opens a port on all interfaces. If your
server has access to the Internet, ensure your firewall is configured
appropriately to limit access to this port as necessary. (You may also list
explicit addresses and subnets to listen. See the postgresql documentation
for more details.)</p>
</div>
<p>Finally, modify the <code class="docutils literal notranslate"><span class="pre">pg_hba.conf</span></code> (in the same directory as <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code>).
Look for a line with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># IPv4 local connections:</span>
<span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">127.0.0.1</span><span class="o">/</span><span class="mi">32</span> <span class="n">md5</span>
</pre></div>
</div>
<p>Add a line with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">host</span> <span class="nb">all</span> <span class="nb">all</span> <span class="mf">0.0.0.0</span><span class="o">/</span><span class="mi">0</span> <span class="n">md5</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This permits incoming connections from <em>all</em> IPs. See
the PosgreSQL documentation on how to limit this.</p>
</div>
<p>Now, restart your cluster:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pg_ctlcluster <span class="m">12</span> main restart
</pre></div>
</div>
<p>Finally, update the database settings in your Evennia secret_settings.py (as
described <a class="reference internal" href="#evennia-postgresql-configuration"><span class="std std-doc">above</span></a> modifying <code class="docutils literal notranslate"><span class="pre">SERVER</span></code> and
<code class="docutils literal notranslate"><span class="pre">PORT</span></code> to match your server.</p>
<p>Now your Evennia installation should be able to connect and talk with a remote
server.</p>
</section>
</section>
<section id="mysql-mariadb">
<h2>MySQL / MariaDB<a class="headerlink" href="#mysql-mariadb" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.mysql.com/">MySQL</a> is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called <a class="reference external" href="https://mariadb.org/">MariaDB</a> that mimics
all functionality and command syntax of the former. So this section covers both.</p>
<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"><div class="highlight"><pre><span></span>mysql -u root -p
</pre></div>
</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"><div class="highlight"><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="s1">&#39;evennia&#39;</span><span class="o">@</span><span class="s1">&#39;localhost&#39;</span><span class="w"> </span><span class="n">IDENTIFIED</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="s1">&#39;somepassword&#39;</span><span class="p">;</span><span class="w"></span>
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">evennia</span><span class="p">;</span><span class="w"></span>
<span class="k">ALTER</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="o">`</span><span class="n">evennia</span><span class="o">`</span><span class="w"> </span><span class="nb">CHARACTER</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="n">utf8</span><span class="p">;</span><span class="w"> </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="w"></span>
<span class="k">GRANT</span><span class="w"> </span><span class="k">ALL</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="n">evennia</span><span class="p">.</span><span class="o">*</span><span class="w"> </span><span class="k">TO</span><span class="w"> </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="w"></span>
<span class="n">FLUSH</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="p">;</span><span class="w"></span>
<span class="c1">-- use &#39;exit&#39; to quit client</span>
</pre></div>
</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>
</section>
</section>
<section id="add-mysql-configuration-to-evennia">
<h2>Add MySQL configuration to Evennia<a class="headerlink" href="#add-mysql-configuration-to-evennia" title="Permalink to this headline"></a></h2>
<p>To tell Evennia to use your new database you need to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> (or
<code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code> if you don’t want your db info passed around on git repositories).</p>
<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"><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>
</div>
<p>Change this to fit your database setup. Next, run:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</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-none notranslate"><div class="highlight"><pre><span></span>evennia dbshell
</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>
</section>
<section id="others">
<h2>Others<a class="headerlink" href="#others" title="Permalink to this headline"></a></h2>
<p>No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for <a class="reference external" href="https://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>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Evennia-Game-Index.html" title="Evennia Game Index"
>next</a> |</li>
<li class="right" >
<a href="Settings-Default.html" title="Evennia Default settings file"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Choosing An SQL Server</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,300 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Client Support Grid &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Online Setup" href="Online-Setup.html" />
<link rel="prev" title="How to connect Evennia to Twitter" href="How-to-connect-Evennia-to-Twitter.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="right" >
<a href="Online-Setup.html" title="Online Setup"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="How-to-connect-Evennia-to-Twitter.html" title="How to connect Evennia to Twitter"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Client Support Grid</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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="#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>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="How-to-connect-Evennia-to-Twitter.html"
title="previous chapter">How to connect Evennia to Twitter</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Online-Setup.html"
title="next chapter">Online Setup</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Client-Support-Grid.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="client-support-grid">
<h1>Client Support Grid<a class="headerlink" href="#client-support-grid" title="Permalink to this headline"></a></h1>
<p>This grid tries to gather info about different MU clients when used with Evennia.
If you want to report a problem, update an entry or add a client, make a
new <a class="reference external" href="https://github.com/evennia/evennia/issues/new/choose">documentation issue</a> for it. Everyone’s encouraged to report their findings.</p>
<section id="client-grid">
<h2>Client Grid<a class="headerlink" href="#client-grid" title="Permalink to this headline"></a></h2>
<p>Legend:</p>
<ul class="simple">
<li><p><strong>Name</strong>: The name of the client. Also note if it’s OS-specific.</p></li>
<li><p><strong>Version</strong>: Which version or range of client versions were tested.</p></li>
<li><p><strong>Comments</strong>: Any quirks on using this client with Evennia should be added here.</p></li>
</ul>
<table class="colwidths-auto docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Name</p></th>
<th class="head"><p>Version tested</p></th>
<th class="head"><p>Comments</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference internal" href="../Components/Webclient.html"><span class="doc std std-doc">Evennia Webclient</span></a></p></td>
<td><p>1.0+</p></td>
<td><p>Evennia-specific</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="http://tintin.sourceforge.net/">tintin++</a></p></td>
<td><p>2.0+</p></td>
<td><p>No MXP support</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="http://tinyfugue.sourceforge.net/">tinyfugue</a></p></td>
<td><p>5.0+</p></td>
<td><p>No UTF-8 support</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://mushclient.com/">MUSHclient</a> (Win)</p></td>
<td><p>4.94</p></td>
<td><p>NAWS reports full text area</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="http://forums.zuggsoft.com/index.php?page=4&amp;action=file&amp;file_id=65">Zmud</a> (Win)</p></td>
<td><p>7.21</p></td>
<td><p><em>UNTESTED</em></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="http://forums.zuggsoft.com/index.php?page=4&amp;action=category&amp;cat_id=11">Cmud</a> (Win)</p></td>
<td><p>v3</p></td>
<td><p><em>UNTESTED</em></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.potatomushclient.com/">Potato</a>_</p></td>
<td><p>2.0.0b16</p></td>
<td><p>No MXP, MCCP support. Win 32bit does not understand</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p>“localhost”, must use <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.mudlet.org/">Mudlet</a></p></td>
<td><p>3.4+</p></td>
<td><p>No known issues. Some older versions showed &lt;&gt; as html</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p>under MXP.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://archive.org/details/tucows_196173_SimpleMU_MU_Client">SimpleMU</a> (Win)</p></td>
<td><p>full</p></td>
<td><p>Discontinued. NAWS reports pixel size.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.riverdark.net/atlantis/">Atlantis</a> (Mac)</p></td>
<td><p>0.9.9.4</p></td>
<td><p>No known issues.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://sourceforge.net/projects/g-mud/">GMUD</a></p></td>
<td><p>0.0.1</p></td>
<td><p>Can’t handle any telnet handshakes. Not recommended.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="http://www.beipmu.com/">BeipMU</a> (Win)</p></td>
<td><p>3.0.255</p></td>
<td><p>No MXP support. Best to enable “MUD prompt handling”, disable</p></td>
</tr>
<tr class="row-even"><td><p></p></td>
<td><p></p></td>
<td><p>“Handle HTML tags”.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://itunes.apple.com/us/app/mudrammer-a-modern-mud-client/id597157072">MudRammer</a> (IOS)</p></td>
<td><p>1.8.7</p></td>
<td><p>Bad Telnet Protocol compliance: displays spurious characters.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://itunes.apple.com/us/app/mudmaster/id341160033">MUDMaster</a></p></td>
<td><p>1.3.1</p></td>
<td><p><em>UNTESTED</em></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://bt.happygoatstudios.com/">BlowTorch</a> (Andr)</p></td>
<td><p>1.1.3</p></td>
<td><p>Telnet NOP displays as spurious character.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://play.google.com/store/apps/details?id=com.crap.mukluk">Mukluk</a> (Andr)</p></td>
<td><p>2015.11.20</p></td>
<td><p>Telnet NOP displays as spurious character. Has UTF-8/Emoji</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p>support.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://github.com/GNOME/gnome-mud">Gnome-MUD</a> (Unix)</p></td>
<td><p>0.11.2</p></td>
<td><p>Telnet handshake errors. First (only) attempt at logging in</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p>fails.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://spyrit.ierne.eu.org/">Spyrit</a></p></td>
<td><p>0.4</p></td>
<td><p>No MXP, OOB support.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://jamochamud.org/">JamochaMUD</a></p></td>
<td><p>5.2</p></td>
<td><p>Does not support ANSI within MXP text.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="http://duckclient.com/">DuckClient</a> (Chrome)</p></td>
<td><p>4.2</p></td>
<td><p>No MXP support. Displays Telnet Go-Ahead and</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p>WILL SUPPRESS-GO-AHEAD as ù character. Also seems to run</p></td>
</tr>
<tr class="row-even"><td><p></p></td>
<td><p></p></td>
<td><p>the <code class="docutils literal notranslate"><span class="pre">version</span></code> command on connection, which will not work in</p></td>
</tr>
<tr class="row-odd"><td><p></p></td>
<td><p></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">MULTISESSION_MODES</span></code> above 1.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.kildclient.org/">KildClient</a></p></td>
<td><p>2.11.1</p></td>
<td><p>No known issues.</p></td>
</tr>
</tbody>
</table>
</section>
<section id="workarounds-for-client-issues">
<h2>Workarounds for client issues:<a class="headerlink" href="#workarounds-for-client-issues" title="Permalink to this headline"></a></h2>
<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>BlowTorch (Andr)</p></li>
<li><p>Mukluk (Andr)</p></li>
</ul>
<p>Workaround:</p>
<ul class="simple">
<li><p>In-game: Use <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 Evennia account permanently.</p></li>
<li><p>Client-side: Set a gag-type trigger on the NOP character to make it invisible to the client.</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Online-Setup.html" title="Online Setup"
>next</a> |</li>
<li class="right" >
<a href="How-to-connect-Evennia-to-Twitter.html" title="How to connect Evennia to Twitter"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Client Support Grid</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,210 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Evennia Game Index &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="IRC" href="IRC.html" />
<link rel="prev" title="Choosing An SQL Server" href="Choosing-An-SQL-Server.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="right" >
<a href="IRC.html" title="IRC"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Choosing-An-SQL-Server.html" title="Choosing An SQL Server"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Game Index</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Choosing-An-SQL-Server.html"
title="previous chapter">Choosing An SQL Server</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="IRC.html"
title="next chapter">IRC</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Evennia-Game-Index.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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>
<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-none notranslate"><div class="highlight"><pre><span></span>evennia connections
</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>
</section>
<section id="manual-settings">
<h2>Manual Settings<a class="headerlink" href="#manual-settings" title="Permalink to this headline"></a></h2>
<p>If you don’t want to use the wizard (maybe because you already have the client installed from an
earlier version), you can also configure your index entry in your settings file
(<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>). Add the following:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">GAME_INDEX_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">GAME_INDEX_LISTING</span> <span class="o">=</span> <span class="p">{</span>
<span class="c1"># required </span>
<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](https://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>
</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>
</section>
<section id="non-public-games">
<h2>Non-public games<a class="headerlink" href="#non-public-games" title="Permalink to this headline"></a></h2>
<p>If you don’t specify neither <code class="docutils literal notranslate"><span class="pre">telnet_hostname</span> <span class="pre">+</span> <span class="pre">port</span></code> nor
<code class="docutils literal notranslate"><span class="pre">web_client_url</span></code>, the Game index will list your game as <em>Not yet public</em>.
Non-public games are moved to the bottom of the index since there is no way
for people to try them out. But it’s a good way to show you are out there, even
if you are not ready for players yet.</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="IRC.html" title="IRC"
>next</a> |</li>
<li class="right" >
<a href="Choosing-An-SQL-Server.html" title="Choosing An SQL Server"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Game Index</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,201 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Grapevine &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="RSS" href="RSS.html" />
<link rel="prev" title="IRC" href="IRC.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="right" >
<a href="RSS.html" title="RSS"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="IRC.html" title="IRC"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Grapevine</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="IRC.html"
title="previous chapter">IRC</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="RSS.html"
title="next chapter">RSS</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Grapevine.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="grapevine">
<h1>Grapevine<a class="headerlink" href="#grapevine" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://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>
<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-none notranslate"><div class="highlight"><pre><span></span>pip install pyopenssl
</pre></div>
</div>
<p>To configure Grapevine, you’ll need to activate it in your settings file.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">GRAPEVINE_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</div>
<p>Next, register an account at <a class="reference external" href="https://grapevine.haus">https://grapevine.haus</a>. 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"><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>
</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: <a class="reference external" href="https://grapevine.haus/chat">https://grapevine.haus/chat</a>.</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-none notranslate"><div class="highlight"><pre><span></span> @grapevine2chan[/switches] &lt;evennia_channel&gt; = &lt;grapevine_channel&gt;
</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>
</section>
<section id="setting-up-grapevine-step-by-step">
<h2>Setting up Grapevine, step by step<a class="headerlink" href="#setting-up-grapevine-step-by-step" title="Permalink to this headline"></a></h2>
<p>You can connect Grapevine to any Evennia channel (so you could connect it to
the default <em>public</em> channel if you like), but for testing, let’s set up a
new channel <code class="docutils literal notranslate"><span class="pre">gw</span></code>.</p>
<div class="highlight-none 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-none notranslate"><div class="highlight"><pre><span></span> @grapevine2chan gw = gossip
</pre></div>
</div>
<p>Evennia will now create a new connection and connect it to Grapevine. Connect
to <a class="reference external" href="https://grapevine.haus/chat">https://grapevine.haus/chat</a> 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>
</section>
</section>
</div>
</div>
</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="right" >
<a href="RSS.html" title="RSS"
>next</a> |</li>
<li class="right" >
<a href="IRC.html" title="IRC"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Grapevine</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,367 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together &#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" />
<link rel="next" title="Apache Config" href="Apache-Config.html" />
<link rel="prev" title="Security" href="Security.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="right" >
<a href="Apache-Config.html" title="Apache Config"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Security.html" title="Security"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a><ul>
<li><a class="reference internal" href="#getting-certificates">Getting certificates</a></li>
<li><a class="reference internal" href="#installing-and-configuring-haproxy">Installing and configuring HAProxy</a></li>
<li><a class="reference internal" href="#putting-it-all-together">Putting it all together</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Security.html"
title="previous chapter">Security</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Apache-Config.html"
title="next chapter">Apache Config</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="HAProxy-Config.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="making-evennia-https-and-wss-secure-websockets-play-nicely-together">
<h1>Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together<a class="headerlink" href="#making-evennia-https-and-wss-secure-websockets-play-nicely-together" title="Permalink to this headline"></a></h1>
<p>A modern public-facing website should these days be served via encrypted
connections. So <code class="docutils literal notranslate"><span class="pre">https:</span></code> rather than <code class="docutils literal notranslate"><span class="pre">http:</span></code> for the website and
<code class="docutils literal notranslate"><span class="pre">wss:</span></code> rather than vs <code class="docutils literal notranslate"><span class="pre">ws:</span></code> for websocket connections used by webclient.</p>
<p>The reason is security - not only does it make sure a user ends up at the right
site (rather than a spoof that hijacked the original’s address), it stops an
evil middleman from snooping on data (like passwords) being sent across the
wire.</p>
<p>Evennia itself does not implement https/wss connections. This is something best
handled by dedicated tools able to keep up-to-date with the latest security
practices.</p>
<p>So what we’ll do is install <em>proxy</em> between Evennia and the outgoing ports of
your server. Essentially, Evennia will think it’s only running locally (on
localhost, IP 127.0.0.1) while the proxy will transparently map that to the
“real” outgoing ports and handle HTTPS/WSS for us.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> Evennia
|
(inside-only local IP/ports serving HTTP/WS)
|
Proxy
|
(outside-visible public IP/ports serving HTTPS/WSS)
|
Firewall
|
Internet
</pre></div>
</div>
<p>These instructions assume you run a server with Unix/Linux (very common if you
use remote hosting) and that you have root access to that server.</p>
<p>The pieces we’ll need:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.haproxy.org/">HAProxy</a> - an open-source proxy program that is
easy to set up and use.</p></li>
<li><p><a class="reference external" href="https://letsencrypt.org/getting-started/">LetsEncrypt</a> for providing the User
Certificate needed to establish an encrypted connection. In particular we’ll
use the excellent <a class="reference external" href="https://certbot.eff.org/instructions">Certbot</a> program,
which automates the whole certificate setup process with LetsEncrypt.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cron</span></code> - this comes with all Linux/Unix systems and allows to automate tasks
in the OS.</p></li>
</ul>
<p>Before starting you also need the following information and setup:</p>
<ul class="simple">
<li><p>(optional) The host name of your game. This is
something you must previously have purchased from a <em>domain registrar</em> and set
up with DNS to point to the IP of your server. For the benefit of this
manual, we’ll assume your host name is <code class="docutils literal notranslate"><span class="pre">my.awesomegame.com</span></code>.</p></li>
<li><p>If you don’t have a domain name or haven’t set it up yet, you must at least
know the IP address of your server. Find this with <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> or similar from
inside the server. If you use a hosting service like DigitalOcean you can also
find the droplet’s IP address in the control panel. Use this as the host name
everywhere.</p></li>
<li><p>You must open port 80 in your firewall. This is used by Certbot below to
auto-renew certificates. So you can’t really run another webserver alongside
this setup without tweaking.</p></li>
<li><p>You must open port 443 (HTTPS) in your firewall. This will be the external
webserver port.</p></li>
<li><p>Make sure port 4001 (internal webserver port) is <em>not</em> open in your firewall
(it usually will be closed by default unless you explicitly opened it
previously).</p></li>
<li><p>Open port 4002 in firewall (we’ll use the same number for both internal-
and external ports, the proxy will only show the safe one serving wss).</p></li>
</ul>
<section id="getting-certificates">
<h2>Getting certificates<a class="headerlink" href="#getting-certificates" title="Permalink to this headline"></a></h2>
<p>Certificates guarantee that you are you. Easiest is to get this with
<a class="reference external" href="https://letsencrypt.org/getting-started/">Letsencrypt</a> and the
<a class="reference external" href="https://certbot.eff.org/instructions">Certbot</a> program. Certbot has a lot of
install instructions for various operating systems. Here’s for Debian/Ubuntu:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo apt install certbot
</pre></div>
</div>
<p>Make sure to stop Evennia and that no port-80 using service is running, then</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo certbot certonly --standalone
</pre></div>
</div>
<p>You will get some questions you need to answer, such as an email to send
certificate errors to and the host name (or IP, supposedly) to use with this
certificate. After this, the certificates will end up in
<code class="docutils literal notranslate"><span class="pre">/etc/letsencrypt/live/&lt;yourhostname&gt;/*pem</span></code> (example from Ubuntu). The
critical files for our purposes are <code class="docutils literal notranslate"><span class="pre">fullchain.pem</span></code> and <code class="docutils literal notranslate"><span class="pre">privkey.pem</span></code>.</p>
<p>Certbot sets up a cron-job/systemd job to regularly renew the certificate. To
check this works, try</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">certbot</span> <span class="n">renew</span> <span class="o">--</span><span class="n">dry</span><span class="o">-</span><span class="n">run</span>
</pre></div>
</div>
<p>The certificate is only valid for 3 months at a time, so make sure this test
works (it requires port 80 to be open). Look up Certbot’s page for more help.</p>
<p>We are not quite done. HAProxy expects these two files to be <em>one</em> file. More
specifically we are going to</p>
<ol class="simple">
<li><p>copy <code class="docutils literal notranslate"><span class="pre">privkey.pem</span></code> and copy it to a new file named <code class="docutils literal notranslate"><span class="pre">&lt;yourhostname&gt;.pem</span></code> (like
<code class="docutils literal notranslate"><span class="pre">my.awesomegame.com.pem</span></code>)</p></li>
<li><p>Append the contents of <code class="docutils literal notranslate"><span class="pre">fullchain.pem</span></code> to the end of this new file. No empty
lines are needed.</p></li>
</ol>
<p>We could do this by copy&amp;pasting in a text editor, but here’s how to do it with
shell commands (replace the example paths with your own):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd /etc/letsencrypt/live/my.awesomegame.com/
sudo cp privkey.pem my.awesomegame.com.pem
sudo cat fullchain.pem &gt;&gt; my.awesomegame.com.pem
</pre></div>
</div>
<p>The new <code class="docutils literal notranslate"><span class="pre">my.awesomegame.com.pem</span></code> file (or whatever you named it) is what we will
point to in the HAProxy config below.</p>
<p>There is a problem here though - Certbot will (re)generate <code class="docutils literal notranslate"><span class="pre">fullchain.pem</span></code> for
us automatically a few days before before the 3-month certificate runs out.
But HAProxy will not see this because it is looking at the combined file that
will still have the old <code class="docutils literal notranslate"><span class="pre">fullchain.pem</span></code> appended to it.</p>
<p>We’ll set up an automated task to rebuild the <code class="docutils literal notranslate"><span class="pre">.pem</span></code> file regularly by
using the <code class="docutils literal notranslate"><span class="pre">cron</span></code> program of Unix/Linux.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>crontab -e
</pre></div>
</div>
<p>An editor will open to the crontab file. Add the following at the bottom (all
on one line, and change the paths to your own!):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>0 5 * * * cd /etc/letsencrypt/live/my.awesomegame.com/ &amp;&amp;
cp privkey.pem my.awesomegame.com.pem &amp;&amp;
cat fullchain.pem &gt;&gt; my.awesomegame.com.pem
</pre></div>
</div>
<p>Save and close the editor. Every night at 05:00 (5 AM), the
<code class="docutils literal notranslate"><span class="pre">my.awesomegame.com.pem</span></code> will now be rebuilt for you. Since Certbot updates
the <code class="docutils literal notranslate"><span class="pre">fullchain.pem</span></code> file a few days before the certificate runs out, this should
be enough time to make sure HaProxy never sees an outdated certificate.</p>
</section>
<section id="installing-and-configuring-haproxy">
<h2>Installing and configuring HAProxy<a class="headerlink" href="#installing-and-configuring-haproxy" title="Permalink to this headline"></a></h2>
<p>Installing HaProxy is usually as simple as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Debian derivatives (Ubuntu, Mint etc)
sudo apt install haproxy
# Redhat derivatives (dnf instead of yum for very recent Fedora distros)
sudo yum install haproxy
</pre></div>
</div>
<p>Configuration of HAProxy is done in a single file. This can be located wherever
you like, for now put in your game dir and name it <code class="docutils literal notranslate"><span class="pre">haproxy.cfg</span></code>.</p>
<p>Here is an example tested on Centos7 and Ubuntu. Make sure to change the file to
put in your own values.</p>
<p>We use the <code class="docutils literal notranslate"><span class="pre">my.awesomegame.com</span></code> example here and here are the ports</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">443</span></code> is the standard SSL port</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">4001</span></code> is the standard Evennia webserver port (firewall closed!)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">4002</span></code> is the default Evennia websocket port (we use the same number for
the outgoing wss port, so this should be open in firewall).</p></li>
</ul>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># base stuff to set up haproxy</span>
global
log /dev/log local0
chroot /var/lib/haproxy
maxconn <span class="m">4000</span>
user haproxy
tune.ssl.default-dh-param <span class="m">2048</span>
<span class="c1">## uncomment this when everything works</span>
<span class="c1"># daemon</span>
defaults
mode http
option forwardfor
<span class="c1"># Evennia Specifics</span>
listen evennia-https-website
<span class="nb">bind</span> my.awesomegame.com:443 ssl no-sslv3 no-tlsv10 crt /etc/letsencrypt/live/my.awesomegame.com&gt;/my.awesomegame.com.pem
server localhost <span class="m">127</span>.0.0.1:4001
timeout client 10m
timeout server 10m
timeout connect 5m
listen evennia-secure-websocket
<span class="nb">bind</span> my.awesomegame.com:4002 ssl no-sslv3 no-tlsv10 crt /etc/letsencrypt/live/my.awesomegame.com/my.awesomegame.com.pem
server localhost <span class="m">127</span>.0.0.1:4002
timeout client 10m
timeout server 10m
timeout connect 5m
</pre></div>
</div>
</section>
<section id="putting-it-all-together">
<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline"></a></h2>
<p>Get back to the Evennia game dir and edit mygame/server/conf/settings.py. Add:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>WEBSERVER_INTERFACES = [&#39;127.0.0.1&#39;]
WEBSOCKET_CLIENT_INTERFACE = &#39;127.0.0.1&#39;
</pre></div>
</div>
<p>and</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>WEBSOCKET_CLIENT_URL=&quot;wss://my.awesomegame.com:4002/&quot;
</pre></div>
</div>
<p>Make sure to reboot (stop + start) evennia completely:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia reboot
</pre></div>
</div>
<p>Finally you start the proxy:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</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">the</span><span class="o">/</span><span class="n">above</span><span class="o">/</span><span class="n">haproxy</span><span class="o">.</span><span class="n">cfg</span>
</pre></div>
</div>
<p>Make sure you can connect to your game from your browser and that you end up
with an <code class="docutils literal notranslate"><span class="pre">https://</span></code> page and can use the websocket webclient.</p>
<p>Once everything works you may want to start the proxy automatically and in the
background. Stop the proxy with <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> and make sure to uncomment the line <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">daemon</span></code> in the config file.</p>
<p>If you have no other proxies running on your server, you can copy your
haproxy.conf file to the system-wide settings:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo cp /path/to/the/above/haproxy.cfg /etc/haproxy/
</pre></div>
</div>
<p>The proxy will now start on reload and you can control it with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo service haproxy start|stop|restart|status
</pre></div>
</div>
<p>If you don’t want to copy stuff into <code class="docutils literal notranslate"><span class="pre">/etc/</span></code> you can also run the haproxy purely
out of your current location by running it with <code class="docutils literal notranslate"><span class="pre">cron</span></code> on server restart. Open
the crontab again:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo crontab -e
</pre></div>
</div>
<p>Add a new line to the end of the file:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@reboot haproxy -f /path/to/the/above/haproxy.cfg
</pre></div>
</div>
<p>Save the file and haproxy should start up automatically when you reboot the
server. Next just restart the proxy manually a last time - with <code class="docutils literal notranslate"><span class="pre">daemon</span></code>
uncommented in the config file, it will now start as a background process.</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Apache-Config.html" title="Apache Config"
>next</a> |</li>
<li class="right" >
<a href="Security.html" title="Security"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,241 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>How to connect Evennia to Twitter &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Client Support Grid" href="Client-Support-Grid.html" />
<link rel="prev" title="RSS" href="RSS.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="right" >
<a href="Client-Support-Grid.html" title="Client Support Grid"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="RSS.html" title="RSS"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">How to connect Evennia to Twitter</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="RSS.html"
title="previous chapter">RSS</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Client-Support-Grid.html"
title="next chapter">Client Support Grid</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<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.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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="https://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>
<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>
</section>
<section id="install-the-twitter-python-module">
<h2>Install the twitter python module<a class="headerlink" href="#install-the-twitter-python-module" title="Permalink to this headline"></a></h2>
<p>To use Twitter you must install the <a class="reference external" href="https://pypi.python.org/pypi/twitter">Twitter</a> Python module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">twitter</span>
</pre></div>
</div>
</section>
<section id="a-basic-tweet-command">
<h2>A basic tweet command<a class="headerlink" href="#a-basic-tweet-command" title="Permalink to this headline"></a></h2>
<p>Evennia doesn’t have a <code class="docutils literal notranslate"><span class="pre">tweet</span></code> command out of the box so you need to write your own little
<a class="reference internal" href="../Components/Commands.html"><span class="doc std std-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="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-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"><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="sa">f</span><span class="s2">&quot;Your tweet was </span><span class="si">{</span><span class="n">tlen</span><span class="si">}</span><span class="s2"> chars long (max 280).&quot;</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="sa">f</span><span class="s2">&quot;You tweeted:</span><span class="se">\n</span><span class="si">{</span><span class="n">tweet</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</pre></div>
</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 std std-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>
</section>
<section id="next-steps">
<h2>Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline"></a></h2>
<p>This shows only a basic tweet setup, other things to do could be:</p>
<ul class="simple">
<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="../Howtos/Tutorial-Tweeting-Game-Stats.html"><span class="doc std std-doc">Tweeting Game Stats tutorial</span></a> for
help.</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Client-Support-Grid.html" title="Client Support Grid"
>next</a> |</li>
<li class="right" >
<a href="RSS.html" title="RSS"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">How to connect Evennia to Twitter</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,217 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>IRC &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Grapevine" href="Grapevine.html" />
<link rel="prev" title="Evennia Game Index" href="Evennia-Game-Index.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="right" >
<a href="Grapevine.html" title="Grapevine"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Evennia-Game-Index.html" title="Evennia Game Index"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">IRC</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Evennia-Game-Index.html"
title="previous chapter">Evennia Game Index</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Grapevine.html"
title="next chapter">Grapevine</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="IRC.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="irc">
<h1>IRC<a class="headerlink" href="#irc" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://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/Channels.html"><span class="doc std std-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="https://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>
<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"><div class="highlight"><pre><span></span> <span class="n">IRC_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</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-none notranslate"><div class="highlight"><pre><span></span> @irc2chan[/switches] &lt;evennia_channel&gt; = &lt;ircnetwork&gt; &lt;port&gt; &lt;#irchannel&gt; &lt;botname&gt;
</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>
</section>
<section id="setting-up-irc-step-by-step">
<h2>Setting up IRC, step by step<a class="headerlink" href="#setting-up-irc-step-by-step" title="Permalink to this headline"></a></h2>
<p>You can connect IRC to any Evennia channel (so you could connect it to the default <em>public</em> channel
if you like), but for testing, let’s set up a new channel <code class="docutils literal notranslate"><span class="pre">irc</span></code>.</p>
<div class="highlight-none 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="https://www.irchelp.org/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-none notranslate"><div class="highlight"><pre><span></span> @irc2chan irc = irc.freenode.net 6667 #myevennia-test mud-bot
</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-none 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-none 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-none notranslate"><div class="highlight"><pre><span></span>[irc] Anna@#myevennia-test: Hello!
</pre></div>
</div>
<p>Your Evennia gamers can now chat with users on external IRC channels!</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Grapevine.html" title="Grapevine"
>next</a> |</li>
<li class="right" >
<a href="Evennia-Game-Index.html" title="Evennia Game Index"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">IRC</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

276
docs/1.0-dev/Setup/Installation-Android.html Normal file
View file

@ -0,0 +1,276 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installing on Android &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Upgrading an existing installation" href="Installation-Upgrade.html" />
<link rel="prev" title="Installation Troubleshooting" href="Installation-Troubleshooting.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="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Troubleshooting.html" title="Installation Troubleshooting"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing on Android</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Troubleshooting.html"
title="previous chapter">Installation Troubleshooting</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Upgrade.html"
title="next chapter">Upgrading an existing installation</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Android.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Android.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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="admonition warning">
<p class="admonition-title">Warning</p>
<p>Android installation is experimental and not tested with later versions of Android.
Report your findings.</p>
</div>
<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>
</section>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h2>
<p>To install some of the libraries Evennia requires, namely Pillow and Twisted, we have to first
install some packages they depend on. In Termux, run the following</p>
<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>
<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 internal" href="#troubleshooting"><span class="std std-doc">Troubleshooting</span></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>
</section>
<section id="final-steps">
<h3>Final steps<a class="headerlink" href="#final-steps" title="Permalink to this headline"></a></h3>
<p>At this point, Evennia is installed on your phone! You can now continue with the original
<a class="reference internal" href="Installation.html"><span class="doc std std-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 <a class="reference external" href="http://localhost:4001">http://localhost:4001</a> or point a telnet
client to localhost:4000 and log in with the user you created.</p>
</section>
</section>
<section id="running-evennia">
<h2>Running Evennia<a class="headerlink" href="#running-evennia" title="Permalink to this headline"></a></h2>
<p>When you wish to run Evennia, get into your Termux console and make sure you have activated your
virtualenv as well as are in your game’s directory. You can then run evennia start as normal.</p>
<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 internal" href="Installation-Git.html#linux-install"><span class="std std-doc">Linux Instructions</span></a> for more.</p>
</section>
<section id="caveats">
<h2>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>Android’s os module doesn’t support certain functions - in particular getloadavg. Thusly, running
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>
</section>
<section id="troubleshooting">
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h2>
<p>As time goes by and errors are reported, this section will be added to.</p>
<p>Some steps to try anyway:</p>
<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>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"
>next</a> |</li>
<li class="right" >
<a href="Installation-Troubleshooting.html" title="Installation Troubleshooting"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing on Android</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

410
docs/1.0-dev/Setup/Installation-Docker.html Normal file
View file

@ -0,0 +1,410 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installing with 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" />
<link rel="next" title="Installation Troubleshooting" href="Installation-Troubleshooting.html" />
<link rel="prev" title="Installing with GIT" href="Installation-Git.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="right" >
<a href="Installation-Troubleshooting.html" title="Installation Troubleshooting"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Git.html" title="Installing with GIT"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing with Docker</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installing with Docker</a><ul>
<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>
</ul>
</li>
<li><a class="reference internal" href="#create-your-own-game-image">Create your own game image</a><ul>
<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-dont-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>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Git.html"
title="previous chapter">Installing with GIT</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Troubleshooting.html"
title="next chapter">Installation Troubleshooting</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Docker.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Docker.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="installing-with-docker">
<h1>Installing with Docker<a class="headerlink" href="#installing-with-docker" title="Permalink to this headline"></a></h1>
<p>Evennia releases <a class="reference external" href="https://hub.docker.com/r/evennia/evennia/">docker images</a> which makes
running an Evennia-based game in a Docker container easy.</p>
<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-none notranslate"><div class="highlight"><pre><span></span>docker pull evennia/evennia
</pre></div>
</div>
<p>This will get the latest stable image.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>docker pull evennia/evennia:develop
</pre></div>
</div>
<p>gets the image based off Evennia’s unstable <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch.</p>
<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-bash notranslate"><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>
</div>
<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"><div class="highlight"><pre><span></span>evennia<span class="p">|</span>docker /usr/src/game $
</pre></div>
</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 normal <a class="reference internal" href="Installation.html"><span class="doc std std-doc">game setup</span></a>
instructions (no virtualenv needed).</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>
<p>Below is an explanation of the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span></code> command we used:</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>
<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>
<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-none 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 evennia/evennia evennia start -l
</pre></div>
</div>
<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>
</section>
</section>
<section id="create-your-own-game-image">
<h2>Create your own game image<a class="headerlink" href="#create-your-own-game-image" title="Permalink to this headline"></a></h2>
<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"><div class="highlight"><pre><span></span> docker build -t mydhaccount/mygame .
</pre></div>
</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>
<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>
</section>
<section id="deploy-game-image-for-production">
<h3>Deploy game image for production<a class="headerlink" href="#deploy-game-image-for-production" title="Permalink to this headline"></a></h3>
<p>Each time you rebuild the docker image as per the above instructions, the latest copy of your game
directory is actually copied inside the image (at <code class="docutils literal notranslate"><span class="pre">/usr/src/game/</span></code>). If you don’t mount your on-disk
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"><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>
</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>
</section>
</section>
<section id="how-it-works">
<h2>How it Works<a class="headerlink" href="#how-it-works" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia/evennia</span></code> docker image holds the evennia library and all of its dependencies. It also
has an <code class="docutils literal notranslate"><span class="pre">ONBUILD</span></code> directive which is triggered during builds of images derived from it. This
<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>
<section id="what-if-i-dont-want-latest">
<h3>What if I Don’t Want “LATEST”?<a class="headerlink" href="#what-if-i-dont-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>
</section>
</section>
<section id="additional-creature-comforts">
<h2>Additional Creature Comforts<a class="headerlink" href="#additional-creature-comforts" title="Permalink to this headline"></a></h2>
<p>The Docker ecosystem includes a tool called <code class="docutils literal notranslate"><span class="pre">docker-compose</span></code>, which can orchestrate complex multi-
container applications, or in our case, store the default port and terminal parameters that we want
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>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Troubleshooting.html" title="Installation Troubleshooting"
>next</a> |</li>
<li class="right" >
<a href="Installation-Git.html" title="Installing with GIT"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing with Docker</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

371
docs/1.0-dev/Setup/Installation-Git.html Normal file
View file

@ -0,0 +1,371 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installing with GIT &#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" />
<link rel="next" title="Installing with Docker" href="Installation-Docker.html" />
<link rel="prev" title="Installation" href="Installation.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="right" >
<a href="Installation-Docker.html" title="Installing with Docker"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation.html" title="Installation"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing with GIT</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installing with GIT</a><ul>
<li><a class="reference internal" href="#summary">Summary</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>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation.html"
title="previous chapter">Installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Docker.html"
title="next chapter">Installing with Docker</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Git.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Git.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="installing-with-git">
<h1>Installing with GIT<a class="headerlink" href="#installing-with-git" title="Permalink to this headline"></a></h1>
<p>This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia itself or have an easier time exploring the code. See the basic <a class="reference internal" href="Installation.html"><span class="doc std std-doc">Installation</span></a> for
a quick installation of the library. See the <a class="reference internal" href="Installation-Troubleshooting.html"><span class="doc std std-doc">troubleshooting</span></a> if you run
into trouble.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>If you are converting an existing game from a previous version, <a class="reference internal" href="Installation-Upgrade.html"><span class="doc std std-doc">see here</span></a>.</p>
</div>
<section id="summary">
<h2>Summary<a class="headerlink" href="#summary" 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>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Currently, these instructions will install ‘latest’ (stable) Evennia, which is
the 0.9.5 version. To install 1.0-dev, you need to add a step <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">develop</span></code> between steps
3 and 4 below.</p>
</div>
<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> (a new folder <code class="docutils literal notranslate"><span class="pre">evennia</span></code> is created)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python3.10</span> <span class="pre">-m</span> <span class="pre">venv</span> <span class="pre">evenv</span></code> (a new folder <code class="docutils literal notranslate"><span class="pre">evenv</span></code> is created)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">source</span> <span class="pre">evenv/bin/activate</span></code> (Linux, Mac), <code class="docutils literal notranslate"><span class="pre">evenv\Scripts\activate</span></code> (Windows)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">evennia</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span> <span class="pre">mygame</span></code></p></li>
<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)</p></li>
</ol>
<p>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>
</section>
<section id="linux-install">
<h2>Linux Install<a class="headerlink" href="#linux-install" title="Permalink to this headline"></a></h2>
<p>For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the requirements:</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="mf">.10</span> <span class="n">python3</span><span class="mf">.10</span><span class="o">-</span><span class="n">venv</span> <span class="n">python3</span><span class="mf">.10</span><span class="o">-</span><span class="n">dev</span> <span class="n">gcc</span>
</pre></div>
</div>
<p>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 internal" href="../Glossary.html#virtualenv"><span class="std std-doc">Glossary entry on
virtualenv</span></a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span><span class="mf">.10</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 (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>Test that you can run the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command everywhere while your virtualenv (evenv) is active.</p>
<p>Next you can continue initializing your game from the regular <a class="reference internal" href="Installation.html"><span class="doc std std-doc">Installation instructions</span></a>.</p>
</section>
<section id="mac-install">
<h2>Mac Install<a class="headerlink" href="#mac-install" title="Permalink to this headline"></a></h2>
<p>The Evennia server is a terminal program. Open the terminal e.g. from
<em>Applications-&gt;Utilities-&gt;Terminal</em>. <a class="reference external" href="https://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.</p>
<ul class="simple">
<li><p>Python should already be installed but you must make sure it’s a high enough version - go for
3.10.
(<a class="reference external" href="https://docs.python-guide.org/en/latest/starting/install/osx/">This</a> discusses
how you may upgrade it).</p></li>
<li><p>GIT can be obtained with
<a class="reference external" href="https://code.google.com/p/git-osx-installer/">git-osx-installer</a> or via MacPorts <a class="reference external" href="https://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 internal" href="../Glossary.html#virtualenv"><span class="std std-doc">Glossary entry on virtualenv</span></a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span><span class="mf">.10</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="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>Test that you can run the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command everywhere while your virtualenv (evenv) is active.</p>
<p>Next you can continue initializing your game from the regular <a class="reference internal" href="Installation.html"><span class="doc std std-doc">Installation instructions</span></a>.</p>
</section>
<section id="windows-install">
<h2>Windows Install<a class="headerlink" href="#windows-install" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>If you are running Windows10, consider using the <em>Windows Subsystem for Linux</em>
(<a class="reference external" href="https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux">WSL</a>) instead.
Just set up WSL with an Ubuntu image and 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="https://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. Get Python any version of Python <strong>3.10</strong>, 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="https://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 internal" href="../Glossary.html#virtualenv"><span class="std std-doc">Glossary entry on virtualenv</span></a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span><span class="mf">.10</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>Test that you can run the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command everywhere while your virtualenv (evenv) is active.</p>
<p>Next you can continue initializing your game from the regular <a class="reference internal" href="Installation.html"><span class="doc std std-doc">Installation instructions</span></a>.</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Docker.html" title="Installing with Docker"
>next</a> |</li>
<li class="right" >
<a href="Installation.html" title="Installation"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installing with GIT</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

148
docs/1.0-dev/Setup/Installation-Non-Interactive.html Normal file
View file

@ -0,0 +1,148 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Non-interactive 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" />
<link rel="next" title="Start Stop Reload" href="Start-Stop-Reload.html" />
<link rel="prev" title="Upgrading an existing installation" href="Installation-Upgrade.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="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Non-interactive setup</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Upgrade.html"
title="previous chapter">Upgrading an existing installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Start-Stop-Reload.html"
title="next chapter">Start Stop Reload</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Non-Interactive.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Non-Interactive.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="non-interactive-setup">
<h1>Non-interactive setup<a class="headerlink" href="#non-interactive-setup" title="Permalink to this headline"></a></h1>
<p>The first time you run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code> (just after having created the database), you will be asked
to interactively insert the superuser username, email and password. If you are deploying Evennia
as part of an automatic build script, you don’t want to enter this information manually.</p>
<p>You can have the superuser be created automatically by passing environment variables to your
build script:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">EVENNIA_SUPERUSER_USERNAME</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">EVENNIA_SUPERUSER_PASSWORD</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">EVENNIA_SUPERUSER_EMAIL</span></code> is optional. If not given, empty string is used.</p></li>
</ul>
<p>These envvars will only be used on the <em>very first</em> server start and then ignored. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EVENNIA_SUPERUSER_USERNAME</span><span class="o">=</span><span class="n">myname</span> <span class="n">EVENNIA_SUPERUSER_PASSWORD</span><span class="o">=</span><span class="n">mypwd</span> <span class="n">evennia</span> <span class="n">start</span>
</pre></div>
</div>
</section>
</div>
</div>
</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="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
>next</a> |</li>
<li class="right" >
<a href="Installation-Upgrade.html" title="Upgrading an existing installation"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Non-interactive setup</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

288
docs/1.0-dev/Setup/Installation-Troubleshooting.html Normal file
View file

@ -0,0 +1,288 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installation Troubleshooting &#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" />
<link rel="next" title="Installing on Android" href="Installation-Android.html" />
<link rel="prev" title="Installing with Docker" href="Installation-Docker.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="right" >
<a href="Installation-Android.html" title="Installing on Android"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Docker.html" title="Installing with Docker"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installation Troubleshooting</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installation Troubleshooting</a><ul>
<li><a class="reference internal" href="#check-your-requirements">Check your Requirements</a></li>
<li><a class="reference internal" href="#confusion-of-location-git-installation">Confusion of location (GIT installation)</a></li>
<li><a class="reference internal" href="#virtualenv-setup-fails">Virtualenv setup fails</a></li>
<li><a class="reference internal" href="#localhost-not-found">Localhost not found</a></li>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Docker.html"
title="previous chapter">Installing with Docker</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Android.html"
title="next chapter">Installing on Android</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Troubleshooting.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Troubleshooting.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="installation-troubleshooting">
<h1>Installation Troubleshooting<a class="headerlink" href="#installation-troubleshooting" title="Permalink to this headline"></a></h1>
<p>If you have an issue not covered here, <a class="reference external" href="https://github.com/evennia/evennia/issues/new/choose">please report it</a>
so it can be fixed or a workaround found!</p>
<p>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>
<section id="check-your-requirements">
<h2>Check your Requirements<a class="headerlink" href="#check-your-requirements" title="Permalink to this headline"></a></h2>
<p>Any system that supports Python3.9+ 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 (Win7, Win8, Win10, Win11)</p></li>
<li><p>Mac OSX (&gt;10.5 recommended)</p></li>
<li><p><a class="reference external" href="https://www.python.org">Python</a> (v3.9 and 3.10 are tested)</p>
<ul>
<li><p><a class="reference external" href="https://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="https://twistedmatrix.com">Twisted</a> (v22.0+)</p>
<ul>
<li><p><a class="reference external" href="https://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="https://www.djangoproject.com">Django</a> (v4.0.1+), be warned that latest dev
version is usually untested with Evennia.</p></li>
<li><p><a class="reference external" href="https://git-scm.com/">GIT</a> - version control software used if you want to install the sources
(but also useful to track your own code) - Mac users can use the
<a class="reference external" href="https://code.google.com/p/git-osx-installer/">git-osx-installer</a> or the
<a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">MacPorts version</a>.</p></li>
</ul>
</section>
<section id="confusion-of-location-git-installation">
<h2>Confusion of location (GIT installation)<a class="headerlink" href="#confusion-of-location-git-installation" title="Permalink to this headline"></a></h2>
<p>It’s common to be confused and install Evennia in the wrong location. After following the
<a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">git install</span></a> instructions, the folder structure should look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">muddev</span><span class="o">/</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>The evennia code itself is found inside <code class="docutils literal notranslate"><span class="pre">evennia/evennia/</span></code> (so two levels down). Your settings file
is <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> and the <em>parent</em> setting file is <code class="docutils literal notranslate"><span class="pre">evennia/evennia/settings_default.py</span></code>.</p>
</section>
<section id="virtualenv-setup-fails">
<h2>Virtualenv setup fails<a class="headerlink" href="#virtualenv-setup-fails" title="Permalink to this headline"></a></h2>
<p>When doing the <code class="docutils literal notranslate"><span class="pre">python3.10</span> <span class="pre">-m</span> <span class="pre">venv</span> <span class="pre">evenv</span></code> step, some users report getting an error; something like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Error: Command &#39;[&#39;evenv&#39;, &#39;-Im&#39;, &#39;ensurepip&#39;, &#39;--upgrade&#39;, &#39;--default-pip&#39;]&#39;
returned non-zero exit status 1
</pre></div>
</div>
<p>You can solve this by installing the <code class="docutils literal notranslate"><span class="pre">python3.10-venv</span></code> package or equivalent for your OS. Alternatively
you can bootstrap it in this way:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python3.10 -m --without-pip evenv
</pre></div>
</div>
<p>This should set up the virtualenv without <code class="docutils literal notranslate"><span class="pre">pip</span></code>. Activate the new virtualenv and then install pip from within it:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python -m ensurepip --upgrade
</pre></div>
</div>
<p>If that fails, a worse alternative to try is</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>curl https://bootstrap.pypa.io/get-pip.py | python3.10 (linux/unix/WSL only)
</pre></div>
</div>
<p>Either way, you should now be able to continue with the installation.</p>
</section>
<section id="localhost-not-found">
<h2>Localhost not found<a class="headerlink" href="#localhost-not-found" title="Permalink to this headline"></a></h2>
<p>If <code class="docutils literal notranslate"><span class="pre">localhost</span></code> doesn’t work when trying to connect to your local game, try <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>, which is the same thing.</p>
</section>
<section id="linux-troubleshooting">
<h2>Linux Troubleshooting<a class="headerlink" href="#linux-troubleshooting" title="Permalink to this headline"></a></h2>
<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>When doing a <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">git install</span></a>, some not-updated Linux distributions may give errors
about 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>
</section>
<section id="mac-troubleshooting">
<h2>Mac Troubleshooting<a class="headerlink" href="#mac-troubleshooting" title="Permalink to this headline"></a></h2>
<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>
</section>
<section id="windows-troubleshooting">
<h2>Windows Troubleshooting<a class="headerlink" href="#windows-troubleshooting" title="Permalink to this headline"></a></h2>
<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.</p></li>
<li><p>When installing Python, 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). 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>If you get a <code class="docutils literal notranslate"><span class="pre">command</span> <span class="pre">not</span> <span class="pre">found</span></code> when trying to run the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program after installation, try closing the
Console and starting it again (remember to re-activate the virtualenv!). Sometimes Windows is not updating
its environment properly.</p></li>
<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>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">22.1</span></code> failed, install <code class="docutils literal notranslate"><span class="pre">22.0</span></code> manually with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">twisted==22.0</span></code>. Alternatively you could check that you are using the 64-bit version of Python
and uninstall any 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 with your new Python.</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>
<li><p>Some users have reported issues with Windows WSL and anti-virus software during Evennia
development. Timeout errors and the inability to run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">connections</span></code> may be due to your anti-
virus software interfering. Try disabling or changing your anti-virus software settings.</p></li>
</ul>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Android.html" title="Installing on Android"
>next</a> |</li>
<li class="right" >
<a href="Installation-Docker.html" title="Installing with Docker"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installation Troubleshooting</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

186
docs/1.0-dev/Setup/Installation-Upgrade.html Normal file
View file

@ -0,0 +1,186 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Upgrading an existing installation &#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" />
<link rel="next" title="Non-interactive setup" href="Installation-Non-Interactive.html" />
<link rel="prev" title="Installing on Android" href="Installation-Android.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="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Android.html" title="Installing on Android"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Upgrading an existing installation</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Upgrading an existing installation</a><ul>
<li><a class="reference internal" href="#evennia-v0-9-5-to-1-0">Evennia v0.9.5 to 1.0</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Android.html"
title="previous chapter">Installing on Android</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Non-Interactive.html"
title="next chapter">Non-interactive setup</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation-Upgrade.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation-Upgrade.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="upgrading-an-existing-installation">
<h1>Upgrading an existing installation<a class="headerlink" href="#upgrading-an-existing-installation" title="Permalink to this headline"></a></h1>
<section id="evennia-v0-9-5-to-1-0">
<h2>Evennia v0.9.5 to 1.0<a class="headerlink" href="#evennia-v0-9-5-to-1-0" title="Permalink to this headline"></a></h2>
<p>Prior to 1.0, all Evennia installs were <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">Git-installs</span></a>. These instructions
assume that you have a cloned <code class="docutils literal notranslate"><span class="pre">evennia</span></code> repo and use a virtualenv (best practices).</p>
<ul class="simple">
<li><p>Make sure to stop Evennia 0.9.5 entirely with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">deactivate</span></code> to leave your active virtualenv.</p></li>
<li><p>Make a <em>backup</em> of your entire <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder, just to be sure!</p></li>
<li><p>Delete the old <code class="docutils literal notranslate"><span class="pre">evenv</span></code> folder, or rename it (in case you want to keep using 0.9.5 for a while).</p></li>
<li><p>Install Python 3.10 (recommended) or 3.9. Follow the <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">Git-installation</span></a> for your OS if needed.</p></li>
<li><p>If using virtualenv, make a <em>new</em> one with <code class="docutils literal notranslate"><span class="pre">python3.10</span> <span class="pre">-m</span> <span class="pre">venv</span> <span class="pre">evenv</span></code>, then activate with <code class="docutils literal notranslate"><span class="pre">source</span> <span class="pre">evenv/bin/activate</span></code>
(linux/mac) or <code class="docutils literal notranslate"><span class="pre">\evenv\Script\activate</span></code> (windows)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> into your <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> folder (you want to see the <code class="docutils literal notranslate"><span class="pre">docs/</span></code>, <code class="docutils literal notranslate"><span class="pre">bin/</span></code> directories as well as a nested <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> folder)</p></li>
<li><p><strong>Prior to 1.0 release only</strong> - do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">develop</span></code> to switch to the develop branch. After release, this will
be found on the default master branch.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code></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">.</span></code></p></li>
<li><p>If you want the optional extra libs, do <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements_extra.txt</span></code>.</p></li>
<li><p>Test that you can run the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command.</p></li>
</ul>
<p>If you don’t have anything you want to keep in your existing game dir, you can just start a new onew
using the normal <a class="reference internal" href="Installation.html"><span class="doc std std-doc">install instructions</span></a>. If you want to keep/convert your existing
game dir, continue below.</p>
<ul class="simple">
<li><p>First, make a backup of your exising game dir! If you use version control, make sure to commit your current state.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to your existing 0.9.5-based game folder (like <code class="docutils literal notranslate"><span class="pre">mygame</span></code>.)</p></li>
<li><p>If you have changed <code class="docutils literal notranslate"><span class="pre">mygame/web</span></code>, <em>rename</em> the folder to <code class="docutils literal notranslate"><span class="pre">web_0.9.5</span></code>. If you didn’t change anything (or don’t have
anything you want to keep), you can <em>delete</em> it entirely.</p></li>
<li><p>Copy <code class="docutils literal notranslate"><span class="pre">evennia/evennia/game_template/web</span></code> to <code class="docutils literal notranslate"><span class="pre">mygame/</span></code> (e.g. using <code class="docutils literal notranslate"><span class="pre">cp</span> <span class="pre">-Rf</span></code> or a file manager). This new <code class="docutils literal notranslate"><span class="pre">web</span></code> folder
replaces the old one and has a very different structure.</p></li>
<li><p>It’s possible you need to replace/comment out import and calls to the deprecated
<a class="reference external" href="https://docs.djangoproject.com/en/3.2/ref/urls/#url"><code class="docutils literal notranslate"><span class="pre">django.conf.urls</span></code></a>. The new way to call it is
<a class="reference external" href="https://docs.djangoproject.com/en/4.0/ref/urls/#django.urls.re_path">available here</a>.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code></p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code></p></li>
</ul>
<p>If you made extensive work in your game dir, you may well find that you need to do some (hopefully minor)
changes to your code before it will start with Evennia 1.0. Some important points:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">evennia/contrib/</span></code> folder changed structure - there are now categorized sub-folders, so you have to update
your imports.</p></li>
<li><p>Any <code class="docutils literal notranslate"><span class="pre">web</span></code> changes need to be moved back from your backup into the new structure of <code class="docutils literal notranslate"><span class="pre">web/</span></code> manually.</p></li>
<li><p>See the <a class="reference internal" href="../Coding/Changelog.html"><span class="doc std std-doc">Evennia 1.0 Changelog</span></a> for all changes.</p></li>
</ul>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
>next</a> |</li>
<li class="right" >
<a href="Installation-Android.html" title="Installing on Android"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Upgrading an existing installation</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,252 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Installation &#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" />
<link rel="next" title="Installing with GIT" href="Installation-Git.html" />
<link rel="prev" title="Server Setup and Life" href="Setup-Overview.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="right" >
<a href="Installation-Git.html" title="Installing with GIT"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Setup-Overview.html" title="Server Setup and Life"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installation</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installation</a><ul>
<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="#restarting-and-stopping">Restarting and stopping</a></li>
<li><a class="reference internal" href="#see-server-logs">See server logs</a></li>
<li><a class="reference internal" href="#server-configuration">Server configuration</a></li>
<li><a class="reference internal" href="#register-with-the-evennia-game-index-optional">Register with the Evennia Game Index (optional)</a></li>
<li><a class="reference internal" href="#the-next-steps">The Next steps</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Setup-Overview.html"
title="previous chapter">Server Setup and Life</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation-Git.html"
title="next chapter">Installing with GIT</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Installation.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Installation.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h1>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>pip install evennia is not yet available in develop branch. Use the <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">git installation</span></a>.</p>
</div>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>If you are converting an existing game from a previous version, <a class="reference internal" href="Installation-Upgrade.html"><span class="doc std std-doc">see here</span></a>.</p>
</div>
<ul class="simple">
<li><p>Evennia requires <a class="reference external" href="https://www.python.org/downloads/">Python</a> 3.9 or 3.10.</p></li>
<li><p>Using a <a class="reference internal" href="../Glossary.html#virtualenv"><span class="std std-doc">Python virtualenv</span></a> is highly recommended in order to keep your
Evennia installation independent from the system libraries.</p></li>
<li><p>Don’t install Evennia as
administrator or superuser.</p></li>
</ul>
<p>Evennia is managed from the terminal (console/CMD on Windows). If you have a suitable Python installed, you can install with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install evennia
</pre></div>
</div>
<p>Alternatively, you can <a class="reference internal" href="Installation-Git.html"><span class="doc std std-doc">install Evennia from github</span></a> or use <a class="reference internal" href="Installation-Docker.html"><span class="doc std std-doc">docker</span></a>.</p>
<p>Installing doesn’t make anything visible online. Apart from installation and updating, you can develop your game without any internet connection.</p>
<p>Once installed, 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. If you are using a virtualenv, make sure it’s active whenever you need to use the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command.</p>
<blockquote>
<div><p>Check out <a class="reference internal" href="Installation-Troubleshooting.html"><span class="doc std std-doc">installation troubleshooting</span></a> if you run into problems. Some
users have also experimented with <a class="reference internal" href="Installation-Android.html"><span class="doc std std-doc">installing Evennia on Android</span></a>.</p>
</div></blockquote>
<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-none notranslate"><div class="highlight"><pre><span></span>evennia --init mygame
</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>
</section>
<section id="start-the-new-game">
<h2>Start the new game<a class="headerlink" href="#start-the-new-game" title="Permalink to this headline"></a></h2>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
evennia migrate
</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-none notranslate"><div class="highlight"><pre><span></span>evennia start
</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>
<blockquote>
<div><p>You can also <a class="reference internal" href="Installation-Non-Interactive.html"><span class="doc std std-doc">automate</span></a> the creation of the super user.</p>
</div></blockquote>
<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>
<p>Log in as a new account or use the superuser you just created.</p>
</section>
<section id="restarting-and-stopping">
<h2>Restarting and stopping<a class="headerlink" href="#restarting-and-stopping" title="Permalink to this headline"></a></h2>
<p>You can restart the server without disconnecting players:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia restart
</pre></div>
</div>
<p>To do a full stop and restart (will disconnect players):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia reboot
</pre></div>
</div>
<p>Full stop of the server (use <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">start</span></code> to restart):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia stop
</pre></div>
</div>
</section>
<section id="see-server-logs">
<h2>See server logs<a class="headerlink" href="#see-server-logs" title="Permalink to this headline"></a></h2>
<p>Log files are in <code class="docutils literal notranslate"><span class="pre">mygame/server/logs</span></code>. You can tail them live with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia --log
</pre></div>
</div>
<p>or</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia -l
</pre></div>
</div>
<p>You can start viewing the log immediately when running <code class="docutils literal notranslate"><span class="pre">evennia</span></code> commands, such as</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia start -l
</pre></div>
</div>
<p>To exit the log tailing, 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>
</section>
<section id="server-configuration">
<h2>Server configuration<a class="headerlink" href="#server-configuration" title="Permalink to this headline"></a></h2>
<p>The server configuration file is <code class="docutils literal notranslate"><span class="pre">mygame/server/settings.py</span></code>. It’s empty by default. Copy and change only the settings you want from the <a class="reference internal" href="Settings-Default.html"><span class="doc std std-doc">default settings file</span></a>.</p>
</section>
<section id="register-with-the-evennia-game-index-optional">
<h2>Register with the Evennia Game Index (optional)<a class="headerlink" href="#register-with-the-evennia-game-index-optional" title="Permalink to this headline"></a></h2>
<p>You can optionally let the world know that you are working on a new Evennia-based game by
registering your server with the <em>Evennia game index</em>. You don’t have to be
open for players to do this - you just mark your game as closed and “pre-alpha”.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia connections
</pre></div>
</div>
<p>See <a class="reference internal" href="Evennia-Game-Index.html"><span class="doc std std-doc">here</span></a> for more instructions and please <a class="reference external" href="http:///games.evennia.com">check out the index</a>
beforehand to make sure you don’t pick a game name that is already taken - be nice!</p>
</section>
<section id="the-next-steps">
<h2>The Next steps<a class="headerlink" href="#the-next-steps" title="Permalink to this headline"></a></h2>
<p>You are good to go!</p>
<p>Next, why not head into the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.html"><span class="doc std std-doc">Starting Tutorial</span></a> to learn how to start making your new game!</p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation-Git.html" title="Installing with GIT"
>next</a> |</li>
<li class="right" >
<a href="Setup-Overview.html" title="Server Setup and Life"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Installation</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,627 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Online Setup &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Security" href="Security.html" />
<link rel="prev" title="Client Support Grid" href="Client-Support-Grid.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="right" >
<a href="Security.html" title="Security"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Client-Support-Grid.html" title="Client Support Grid"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Online Setup</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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="#lets-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>
<h4>Previous topic</h4>
<p class="topless"><a href="Client-Support-Grid.html"
title="previous chapter">Client Support Grid</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Security.html"
title="next chapter">Security</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Online-Setup.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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>
<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>
<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 internal" href="Settings.html#settings-file"><span class="std std-doc">settings file</span></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"><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"># This needs to be set to your website address for django or you&#39;ll receive a</span>
<span class="c1"># CSRF error when trying to log on to the web portal</span>
<span class="n">CSRF_TRUSTED_ORIGINS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;https://mymudgame.com&#39;</span><span class="p">]</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>
</div>
<p>Read on for a description of the individual settings.</p>
</section>
<section id="telnet">
<h3>Telnet<a class="headerlink" href="#telnet" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><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>
</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>
</section>
<section id="web-server">
<h3>Web server<a class="headerlink" href="#web-server" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><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>
</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>
</section>
<section id="web-client">
<h3>Web client<a class="headerlink" href="#web-client" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><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>
</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>
</section>
<section id="other-ports">
<h3>Other ports<a class="headerlink" href="#other-ports" title="Permalink to this headline"></a></h3>
<div class="highlight-python notranslate"><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>
</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 std std-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>
</section>
<section id="lockdown-mode">
<h3>Lockdown mode<a class="headerlink" href="#lockdown-mode" title="Permalink to this headline"></a></h3>
<p>When you test things out and check configurations you may not want players to drop in on you.
Similarly, if you are doing maintenance on a live game you may want to take it offline for a while
to fix eventual problems without risking people connecting. To do this, stop the server with
<code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">stop</span></code> and add <code class="docutils literal notranslate"><span class="pre">LOCKDOWN_MODE</span> <span class="pre">=</span> <span class="pre">True</span></code> to your settings file. When you start the server
again, your game will only be accessible from localhost.</p>
</section>
<section id="registering-with-the-evennia-game-directory">
<h3>Registering with the Evennia game directory<a class="headerlink" href="#registering-with-the-evennia-game-directory" title="Permalink to this headline"></a></h3>
<p>Once your game is online you should make sure to register it with the <a class="reference external" href="http://games.evennia.com/">Evennia Game
Index</a>. Registering with the index will help people find your server,
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-none notranslate"><div class="highlight"><pre><span></span>evennia connections
</pre></div>
</div>
<p>and follow the instructions. See the <a class="reference internal" href="Evennia-Game-Index.html"><span class="doc std std-doc">Game index page</span></a> for more details.</p>
</section>
</section>
<section id="ssl">
<h2>SSL<a class="headerlink" href="#ssl" title="Permalink to this headline"></a></h2>
<p>SSL can be very useful for web clients. It will protect the credentials and gameplay of your users
over a web client if they are in a public place, and your websocket can also be switched to WSS for
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>
<section id="lets-encrypt">
<h3>Let’s Encrypt<a class="headerlink" href="#lets-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](<a class="reference external" href="https://www.digitalocean.com/community/tutorials/how-">https://www.digitalocean.com/community/tutorials/how-</a>
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>
</section>
</section>
<section id="relevant-ssl-proxy-setup-information">
<h2>Relevant SSL Proxy Setup Information<a class="headerlink" href="#relevant-ssl-proxy-setup-information" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="Apache-Config.html"><span class="doc std std-doc">Apache webserver configuration</span></a> (optional)</p></li>
<li><p><a class="reference internal" href="HAProxy-Config.html"><span class="doc std std-doc">HAProxy Config</span></a></p></li>
</ul>
</section>
<section id="hosting-locally-or-remotely">
<h2>Hosting locally or remotely?<a class="headerlink" href="#hosting-locally-or-remotely" title="Permalink to this headline"></a></h2>
<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>
<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 internal" href="#connecting-from-the-outside"><span class="std std-doc">The first section</span></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="https://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="https://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>
</section>
</section>
<section id="remote-hosting">
<h3>Remote hosting<a class="headerlink" href="#remote-hosting" title="Permalink to this headline"></a></h3>
<p>Your normal “web hotel” will probably not be enough to run Evennia. A web hotel is normally aimed at
a very specific usage - delivering web pages, at the most with some dynamic content. The “Python
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="Installation-Docker.html"><span class="doc std std-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>
<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="Installation.html"><span class="doc std std-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>
</section>
</section>
<section id="hosting-options">
<h3>Hosting options<a class="headerlink" href="#hosting-options" title="Permalink to this headline"></a></h3>
<p>To find commercial solutions, browse the web for “shell access”, “VPS” or “Cloud services” in your
region. You may find useful offers for “low cost” VPS hosting on <a class="reference external" href="https://lowendbox.com/">Low End Box</a>. The associated
<a class="reference external" href="https://www.lowendtalk.com">Low End Talk</a> 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>
<table class="colwidths-auto docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Hosting name</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Lowest price</p></th>
<th class="head"><p>Comments</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="https://silvren.com">silvren.com</a></p></td>
<td><p>Shell account</p></td>
<td><p>Free for MU*</p></td>
<td><p>Private hobby provider so don’t assume backups or expect immediate support. To ask for an account, connect with a MUD client to <a class="reference external" href="http://rostdev.mushpark.com">rostdev.mushpark.com</a>, port 4201 and ask for “Jarin”.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.digitalocean.com/pricing">Digital Ocean</a></p></td>
<td><p>VPS</p></td>
<td><p>$5/month</p></td>
<td><p>You can get a $50 credit if you use the referral link <a class="reference external" href="https://m.do.co/c/8f64fec2670c">https://m.do.co/c/8f64fec2670c</a> - 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.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://aws.amazon.com/pricing/">Amazon Web services</a></p></td>
<td><p>Cloud</p></td>
<td><p>~$5/month / on-demand</p></td>
<td><p>Free Tier first 12 months. Regions available around the globe.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://amazonlightsail.com">Amazon Lightsail</a></p></td>
<td><p>Cloud</p></td>
<td><p>$5/month</p></td>
<td><p>Free first month. AWS’s “fixed cost” offering.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://azure.microsoft.com/en-us/pricing/details/app-service/windows/">Azure App Services</a></p></td>
<td><p>Cloud</p></td>
<td><p>Free</p></td>
<td><p>Free tier with limited regions for hobbyists.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://activity.huaweicloud.com/intl/en-us/free_packages/index.html">Huawei Cloud</a></p></td>
<td><p>Cloud</p></td>
<td><p>on demand</p></td>
<td><p>Similar to Amazon. Free 12-month tier with limited regions.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.genesismuds.com/">Genesis MUD hosting</a></p></td>
<td><p>Shell account</p></td>
<td><p>$8/month</p></td>
<td><p>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.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.host1plus.com/">Host1Plus</a></p></td>
<td><p>VPS &amp; Cloud</p></td>
<td><p>$4/month</p></td>
<td><p>$4-$8/month depending on length of sign-up period.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.scaleway.com/">Scaleway</a></p></td>
<td><p>Cloud</p></td>
<td><p>€3/month / on-demand</p></td>
<td><p>EU based (Paris, Amsterdam). Smallest option provides 2GB RAM.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://prgmr.com/">Prgmr</a></p></td>
<td><p>VPS</p></td>
<td><p>$5/month</p></td>
<td><p>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.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.linode.com/">Linode</a></p></td>
<td><p>Cloud</p></td>
<td><p>$5/month / on-demand</p></td>
<td><p>Multiple regions. Smallest option provides 1GB RAM</p></td>
</tr>
</tbody>
</table>
<p><em>Please help us expand this list.</em></p>
</section>
</section>
<section id="cloud9">
<h2>Cloud9<a class="headerlink" href="#cloud9" title="Permalink to this headline"></a></h2>
<p>If you are interested in running Evennia in the online dev environment <a class="reference external" href="https://c9.io/">Cloud9</a>, you
can spin it up through their normal online setup using the Evennia Linux install instructions. The
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.
<a class="reference external" href="https://aws.amazon.com/cloud9/">https://aws.amazon.com/cloud9/</a></p>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Security.html" title="Security"
>next</a> |</li>
<li class="right" >
<a href="Client-Support-Grid.html" title="Client Support Grid"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Online Setup</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,187 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>RSS &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="How to connect Evennia to Twitter" href="How-to-connect-Evennia-to-Twitter.html" />
<link rel="prev" title="Grapevine" href="Grapevine.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="right" >
<a href="How-to-connect-Evennia-to-Twitter.html" title="How to connect Evennia to Twitter"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Grapevine.html" title="Grapevine"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">RSS</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Grapevine.html"
title="previous chapter">Grapevine</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="How-to-connect-Evennia-to-Twitter.html"
title="next chapter">How to connect Evennia to Twitter</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="RSS.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="rss">
<h1>RSS<a class="headerlink" href="#rss" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://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="https://code.google.com/feeds/p/evennia/updates/basic">here</a>.</p>
<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="https://code.google.com/p/feedparser/">feedparser</a> python
module.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install feedparser
</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-none notranslate"><div class="highlight"><pre><span></span> @rss2chan &lt;evennia_channel&gt; = &lt;rss_url&gt;
</pre></div>
</div>
<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-none 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-none notranslate"><div class="highlight"><pre><span></span> @rss2chan rss = https://github.com/evennia/evennia/commits/master.atom
</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-none notranslate"><div class="highlight"><pre><span></span> @rss2chan/delete rss = https://github.com/evennia/evennia/commits/master.atom
</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 std std-doc">IRC</span></a> to have the feed echo to external chat channels as well.</p>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="How-to-connect-Evennia-to-Twitter.html" title="How to connect Evennia to Twitter"
>next</a> |</li>
<li class="right" >
<a href="Grapevine.html" title="Grapevine"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">RSS</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,299 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Security &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together" href="HAProxy-Config.html" />
<link rel="prev" title="Online Setup" href="Online-Setup.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="right" >
<a href="HAProxy-Config.html" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Online-Setup.html" title="Online Setup"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Security</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="Online-Setup.html"
title="previous chapter">Online Setup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="HAProxy-Config.html"
title="next chapter">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Security.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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>
<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>
</section>
<section id="disable-development-debugging-options">
<h2>Disable development/debugging options<a class="headerlink" href="#disable-development-debugging-options" title="Permalink to this headline"></a></h2>
<p>There are a few Evennia/Django options that are set when you first create your game to make it more
obvious to you where problems arise. These options should be disabled before you push your game into
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-none notranslate"><div class="highlight"><pre><span></span># Disable Django&#39;s debug mode
DEBUG = False
# Disable the in-game equivalent
IN_GAME_ERRORS = False
# If you&#39;ve registered a domain name, force Django to check host headers. Otherwise leave this
</pre></div>
</div>
<p>as-is.
# Note the leading period– it is not a typo!
ALLOWED_HOSTS = [‘.example.com’]</p>
</section>
<section id="handle-user-uploaded-images-with-care">
<h2>Handle user-uploaded images with care<a class="headerlink" href="#handle-user-uploaded-images-with-care" title="Permalink to this headline"></a></h2>
<p>If you decide to allow users to upload their own images to be served from your site, special care
must be taken. Django will read the file headers to confirm it’s an image (as opposed to a document
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>
</section>
<section id="disable-the-web-interface">
<h2>Disable the web interface<a class="headerlink" href="#disable-the-web-interface" title="Permalink to this headline"></a></h2>
<p>The web interface allows visitors to see an informational page as well as log into a browser-based
telnet client with which to access Evennia. It also provides authentication endpoints against which
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-none notranslate"><div class="highlight"><pre><span></span># Disable the Javascript webclient
WEBCLIENT_ENABLED = False
# Disable the website altogether
WEBSERVER_ENABLED = False
</pre></div>
</div>
</section>
<section id="change-your-ssh-port">
<h2>Change your ssh port<a class="headerlink" href="#change-your-ssh-port" title="Permalink to this headline"></a></h2>
<p>Automated attacks will often target port 22 seeing as how it’s the standard port for SSH traffic.
Also,
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-none notranslate"><div class="highlight"><pre><span></span># What ports, IPs and protocols we listen for
Port 443
</pre></div>
</div>
<p>Save, close, then run the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo service ssh restart
</pre></div>
</div>
</section>
<section id="set-up-a-firewall">
<h2>Set up a firewall<a class="headerlink" href="#set-up-a-firewall" title="Permalink to this headline"></a></h2>
<p>Ubuntu users can make use of the simple ufw utility. Anybody else can use iptables.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Install ufw (if not already)
sudo apt-get install ufw
</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-none notranslate"><div class="highlight"><pre><span></span># Allow terminal connections to your game
sudo ufw allow 4000/tcp
# Allow browser connections to your website
sudo ufw allow 4001/tcp
</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-none notranslate"><div class="highlight"><pre><span></span>sudo ufw allow 22/tcp
sudo ufw allow 443/tcp
</pre></div>
</div>
<p>Finally:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sudo ufw enable
</pre></div>
</div>
<p>Now the only ports open will be your administrative ssh port (whichever you chose), and Evennia on
4000-4001.</p>
</section>
<section id="use-an-external-webserver">
<h2>Use an external webserver<a class="headerlink" href="#use-an-external-webserver" title="Permalink to this headline"></a></h2>
<p>Though not officially supported, there are some benefits to <a class="reference internal" href="Apache-Config.html"><span class="doc std std-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>
</section>
</section>
</div>
</div>
</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="right" >
<a href="HAProxy-Config.html" title="Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together"
>next</a> |</li>
<li class="right" >
<a href="Online-Setup.html" title="Online Setup"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Security</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

1351
docs/1.0-dev/Setup/Settings-Default.html Normal file
View file

File diff suppressed because it is too large Load diff

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

@ -0,0 +1,231 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Game Settings and Configuration direcotry &#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" />
<link rel="next" title="Evennia Default settings file" href="Settings-Default.html" />
<link rel="prev" title="Start Stop Reload" href="Start-Stop-Reload.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="right" >
<a href="Settings-Default.html" title="Evennia Default settings file"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Game Settings and Configuration direcotry</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Game Settings and Configuration direcotry</a><ul>
<li><a class="reference internal" href="#settings-file">Settings file</a></li>
<li><a class="reference internal" href="#other-files-in-the-server-conf-directory">Other files in the <code class="docutils literal notranslate"><span class="pre">server/conf</span></code> directory</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Start-Stop-Reload.html"
title="previous chapter">Start Stop Reload</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Settings-Default.html"
title="next chapter">Evennia Default settings file</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Settings.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Settings.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="game-settings-and-configuration-direcotry">
<h1>Game Settings and Configuration direcotry<a class="headerlink" href="#game-settings-and-configuration-direcotry" title="Permalink to this headline"></a></h1>
<p>Evennia runs out of the box without any changes to its settings. But there are several important
ways to customize the server and expand it with your own plugins.</p>
<p>All game-specific settings are located in the <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code> directory.</p>
<section id="settings-file">
<h2>Settings file<a class="headerlink" href="#settings-file" title="Permalink to this headline"></a></h2>
<p>The “Settings” file referenced throughout the documentation is the file
<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>.</p>
<p>Your new <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> is relatively bare out of the box. Evennia’s core settings file is
the <a class="reference internal" href="Settings-Default.html"><span class="doc std std-doc">Settings-Default file</span></a> and is considerably more extensive. It is also
heavily documented and up-to-date, so you should refer to this file directly for the available settings.</p>
<p>Since <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> is a normal Python module, it simply imports
<code class="docutils literal notranslate"><span class="pre">evennia/settings_default.py</span></code> into itself at the top.</p>
<p>This means that if any setting you want to change were to depend on some <em>other</em> default setting,
you might need to copy &amp; paste both in order to change them and get the effect you want (for most
commonly changed settings, this is not something you need to worry about).</p>
<p>You should never edit <code class="docutils literal notranslate"><span class="pre">evennia/settings_default.py</span></code>. Rather you should copy&amp;paste the select
variables you want to change into your <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> and edit them there. This will overload the
previously imported defaults.</p>
<blockquote>
<div><p>Warning: It may be tempting to copy everything from <code class="docutils literal notranslate"><span class="pre">settings_default.py</span></code> into your own settings
file. There is a reason we don’t do this out of the box though: it makes it directly clear what
changes you did. Also, if you limit your copying to the things you really need you will directly be
able to take advantage of upstream changes and additions to Evennia for anything you didn’t
customize.</p>
</div></blockquote>
<p>In code, the settings is accessed through</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="c1"># or (shorter):</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="c1"># example:</span>
<span class="n">servername</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">SERVER_NAME</span>
</pre></div>
</div>
<p>Each setting appears as a property on the imported <code class="docutils literal notranslate"><span class="pre">settings</span></code> object. You can also explore all
possible options with <code class="docutils literal notranslate"><span class="pre">evennia.settings_full</span></code> (this also includes advanced Django defaults that are
not touched in default Evennia).</p>
<blockquote>
<div><p>When importing <code class="docutils literal notranslate"><span class="pre">settings</span></code> into your code like this, it will be <em>read
only</em>. You <em>cannot</em> edit your settings from your code! The only way to change an Evennia setting is
to edit <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code> directly. You will also need to restart the server
(possibly also the Portal) before a changed setting becomes available.</p>
</div></blockquote>
</section>
<section id="other-files-in-the-server-conf-directory">
<h2>Other files in the <code class="docutils literal notranslate"><span class="pre">server/conf</span></code> directory<a class="headerlink" href="#other-files-in-the-server-conf-directory" title="Permalink to this headline"></a></h2>
<p>Apart from the main <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file,</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">at_initial_setup.py</span></code> - this allows you to add a custom startup method to be called (only) the
very first time Evennia starts (at the same time as user #1 and Limbo is created). It can be made to
start your own global scripts or set up other system/world-related things your game needs to have
running from the start.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">at_server_startstop.py</span></code> - this module contains two functions that Evennia will call every time
the Server starts and stops respectively - this includes stopping due to reloading and resetting as
well as shutting down completely. It’s a useful place to put custom startup code for handlers and
other things that must run in your game but which has no database persistence.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">connection_screens.py</span></code> - all global string variables in this module are interpreted by Evennia as
a greeting screen to show when an Account first connects. If more than one string variable is
present in the module a random one will be picked.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">inlinefuncs.py</span></code> - this is where you can define custom <a class="reference internal" href="../Components/FuncParser.html"><span class="doc std std-doc">FuncParser functions</span></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">inputfuncs.py</span></code> - this is where you define custom <a class="reference internal" href="../Components/Inputfuncs.html"><span class="doc std std-doc">Input functions</span></a> to handle data
from the client.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">lockfuncs.py</span></code> - this is one of many possible modules to hold your own “safe” <em>lock functions</em> to
make available to Evennia’s <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">Locks</span></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mssp.py</span></code> - this holds meta information about your game. It is used by MUD search engines (which
you often have to register with) in order to display what kind of game you are running along with
statistics such as number of online accounts and online status.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">oobfuncs.py</span></code> - in here you can define custom <a class="reference internal" href="../Concepts/OOB.html"><span class="doc std std-doc">OOB functions</span></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">portal_services_plugin.py</span></code> - this allows for adding your own custom services/protocols to the
Portal. It must define one particular function that will be called by Evennia at startup. There can
be any number of service plugin modules, all will be imported and used if defined. More info can be
found <a class="reference external" href="https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols">here</a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">server_services_plugin.py</span></code> - this is equivalent to the previous one, but used for adding new
services to the Server instead. More info can be found
<a class="reference external" href="https://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols">here</a>.</p></li>
</ul>
<p>Some other Evennia systems can be customized by plugin modules but has no explicit template in
<code class="docutils literal notranslate"><span class="pre">conf/</span></code>:</p>
<ul class="simple">
<li><p><em><a class="reference external" href="http://cmdparser.py">cmdparser.py</a></em> - a custom module can be used to totally replace Evennia’s default command parser.
All this does is to split the incoming string into “command name” and “the rest”. It also handles
things like error messages for no-matches and multiple-matches among other things that makes this
more complex than it sounds. The default parser is <em>very</em> generic, so you are most often best served
by modifying things further down the line (on the command parse level) than here.</p></li>
<li><p><em>at_search.py</em> - this allows for replacing the way Evennia handles search results. It allows to
change how errors are echoed and how multi-matches are resolved and reported (like how the default
understands that “2-ball” should match the second “ball” object if there are two of them in the
room).</p></li>
</ul>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Settings-Default.html" title="Evennia Default settings file"
>next</a> |</li>
<li class="right" >
<a href="Start-Stop-Reload.html" title="Start Stop Reload"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Game Settings and Configuration direcotry</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,298 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Server Setup and Life &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Installation" href="Installation.html" />
<link rel="prev" title="Evennia Introduction" href="../Evennia-Introduction.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="right" >
<a href="Installation.html" title="Installation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
accesskey="P">previous</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 class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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="#configuring">Configuring</a></li>
<li><a class="reference internal" href="#going-public">Going public</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../Evennia-Introduction.html"
title="previous chapter">Evennia Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Installation.html"
title="next chapter">Installation</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Setup-Overview.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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 sums up all steps of maintaining your Evennia game from first installation to production release.</p>
<section id="installation-running">
<h2>Installation &amp; running<a class="headerlink" href="#installation-running" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Installation.html">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#initialize-a-new-game">Initialize a new game</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#start-the-new-game">Start the new game</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#restarting-and-stopping">Restarting and stopping</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#see-server-logs">See server logs</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#server-configuration">Server configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#register-with-the-evennia-game-index-optional">Register with the Evennia Game Index (optional)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation.html#the-next-steps">The Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Git.html">Installing with GIT</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation-Git.html#summary">Summary</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Git.html#linux-install">Linux Install</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Git.html#mac-install">Mac Install</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Git.html#windows-install">Windows Install</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Docker.html">Installing with Docker</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation-Docker.html#running-your-game-as-a-docker-image">Running your game as a docker image</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Docker.html#create-your-own-game-image">Create your own game image</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Docker.html#how-it-works">How it Works</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Docker.html#additional-creature-comforts">Additional Creature Comforts</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Troubleshooting.html">Installation Troubleshooting</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#check-your-requirements">Check your Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#confusion-of-location-git-installation">Confusion of location (GIT installation)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#virtualenv-setup-fails">Virtualenv setup fails</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#localhost-not-found">Localhost not found</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#linux-troubleshooting">Linux Troubleshooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#mac-troubleshooting">Mac Troubleshooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Troubleshooting.html#windows-troubleshooting">Windows Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Android.html">Installing on Android</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation-Android.html#install-termux">Install Termux</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Android.html#prerequisites">Prerequisites</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Android.html#running-evennia">Running Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Android.html#caveats">Caveats</a></li>
<li class="toctree-l2"><a class="reference internal" href="Installation-Android.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Upgrade.html">Upgrading an existing installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Installation-Upgrade.html#evennia-v0-9-5-to-1-0">Evennia v0.9.5 to 1.0</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Installation-Non-Interactive.html">Non-interactive setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="Start-Stop-Reload.html">Start Stop Reload</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#starting-evennia">Starting Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#reloading">Reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#stopping">Stopping</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#foreground-mode">Foreground mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#resetting">Resetting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#rebooting">Rebooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#status-and-info">Status and info</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#killing-linux-mac-only">Killing (Linux/Mac only)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#django-options">Django options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Start-Stop-Reload.html#advanced-handling-of-evennia-processes">Advanced handling of Evennia processes</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="configuring">
<h2>Configuring<a class="headerlink" href="#configuring" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Settings.html">Game Settings and Configuration direcotry</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Settings.html#settings-file">Settings file</a></li>
<li class="toctree-l2"><a class="reference internal" href="Settings.html#other-files-in-the-server-conf-directory">Other files in the <code class="docutils literal notranslate"><span class="pre">server/conf</span></code> directory</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Settings-Default.html">Evennia Default settings file</a></li>
<li class="toctree-l1"><a class="reference internal" href="Choosing-An-SQL-Server.html">Choosing An SQL Server</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Choosing-An-SQL-Server.html#sqlite3">SQLite3</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-An-SQL-Server.html#postgresql">PostgreSQL</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-An-SQL-Server.html#mysql-mariadb">MySQL / MariaDB</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-An-SQL-Server.html#add-mysql-configuration-to-evennia">Add MySQL configuration to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Choosing-An-SQL-Server.html#others">Others</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Evennia-Game-Index.html">Evennia Game Index</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Game-Index.html#connect-with-the-wizard">Connect with the wizard</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Game-Index.html#manual-settings">Manual Settings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Game-Index.html#non-public-games">Non-public games</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="IRC.html">IRC</a><ul>
<li class="toctree-l2"><a class="reference internal" href="IRC.html#configuring-irc">Configuring IRC</a></li>
<li class="toctree-l2"><a class="reference internal" href="IRC.html#setting-up-irc-step-by-step">Setting up IRC, step by step</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Grapevine.html">Grapevine</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Grapevine.html#configuring-grapevine">Configuring Grapevine</a></li>
<li class="toctree-l2"><a class="reference internal" href="Grapevine.html#setting-up-grapevine-step-by-step">Setting up Grapevine, step by step</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="RSS.html">RSS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="RSS.html#configuring-rss">Configuring RSS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html">How to connect Evennia to Twitter</a><ul>
<li class="toctree-l2"><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html#configuring-twitter">Configuring Twitter</a></li>
<li class="toctree-l2"><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html#install-the-twitter-python-module">Install the twitter python module</a></li>
<li class="toctree-l2"><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html#a-basic-tweet-command">A basic tweet command</a></li>
<li class="toctree-l2"><a class="reference internal" href="How-to-connect-Evennia-to-Twitter.html#next-steps">Next Steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Client-Support-Grid.html">Client Support Grid</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Client-Support-Grid.html#client-grid">Client Grid</a></li>
<li class="toctree-l2"><a class="reference internal" href="Client-Support-Grid.html#workarounds-for-client-issues">Workarounds for client issues:</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="going-public">
<h2>Going public<a class="headerlink" href="#going-public" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Online-Setup.html">Online Setup</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Online-Setup.html#connecting-from-the-outside">Connecting from the outside</a></li>
<li class="toctree-l2"><a class="reference internal" href="Online-Setup.html#ssl">SSL</a></li>
<li class="toctree-l2"><a class="reference internal" href="Online-Setup.html#relevant-ssl-proxy-setup-information">Relevant SSL Proxy Setup Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="Online-Setup.html#hosting-locally-or-remotely">Hosting locally or remotely?</a></li>
<li class="toctree-l2"><a class="reference internal" href="Online-Setup.html#cloud9">Cloud9</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Security.html">Security</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Security.html#know-your-logs">Know your logs</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#disable-development-debugging-options">Disable development/debugging options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#handle-user-uploaded-images-with-care">Handle user-uploaded images with care</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#disable-the-web-interface">Disable the web interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#change-your-ssh-port">Change your ssh port</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#set-up-a-firewall">Set up a firewall</a></li>
<li class="toctree-l2"><a class="reference internal" href="Security.html#use-an-external-webserver">Use an external webserver</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="HAProxy-Config.html">Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together</a><ul>
<li class="toctree-l2"><a class="reference internal" href="HAProxy-Config.html#getting-certificates">Getting certificates</a></li>
<li class="toctree-l2"><a class="reference internal" href="HAProxy-Config.html#installing-and-configuring-haproxy">Installing and configuring HAProxy</a></li>
<li class="toctree-l2"><a class="reference internal" href="HAProxy-Config.html#putting-it-all-together">Putting it all together</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Apache-Config.html">Apache Config</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Apache-Config.html#mod-wsgi-setup"><code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="Apache-Config.html#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></li>
</ul>
</li>
</ul>
</div>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Installation.html" title="Installation"
>next</a> |</li>
<li class="right" >
<a href="../Evennia-Introduction.html" title="Evennia Introduction"
>previous</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 class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>

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

@ -0,0 +1,327 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Start Stop Reload &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<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" />
<link rel="next" title="Game Settings and Configuration direcotry" href="Settings.html" />
<link rel="prev" title="Non-interactive setup" href="Installation-Non-Interactive.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="right" >
<a href="Settings.html" title="Game Settings and Configuration direcotry"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
accesskey="P">previous</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-1"><a href="Setup-Overview.html" accesskey="U">Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<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>
<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="#reloading">Reloading</a></li>
<li><a class="reference internal" href="#stopping">Stopping</a></li>
<li><a class="reference internal" href="#foreground-mode">Foreground mode</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="#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>
<h4>Previous topic</h4>
<p class="topless"><a href="Installation-Non-Interactive.html"
title="previous chapter">Non-interactive setup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Settings.html"
title="next chapter">Game Settings and Configuration direcotry</a></p>
<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>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Start-Stop-Reload.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" 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 on the <a class="reference internal" href="Installation.html"><span class="doc std std-doc">Installation</span></a> page.</p>
<aside class="sidebar">
<p class="sidebar-title">evennia not found?</p>
<p>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 internal" href="../Glossary.html#virtualenv"><span class="std std-doc">virtualenv</span></a> is active.</p>
</aside>
<p>Below are described the various management options. Run</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia -h
</pre></div>
</div>
<p>to give you a brief help and</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia menu
</pre></div>
</div>
<p>to give you a menu with options.</p>
<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 std std-doc">Portal and Server</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-none notranslate"><div class="highlight"><pre><span></span> evennia start
</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-none notranslate"><div class="highlight"><pre><span></span> evennia -l
</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-none notranslate"><div class="highlight"><pre><span></span> evennia start -l
</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>
</section>
<section id="reloading">
<h2>Reloading<a class="headerlink" href="#reloading" title="Permalink to this headline"></a></h2>
<p>The act of <em>reloading</em> means the Portal will tell the Server to shut down and then boot it back up
again. Everyone will get a message and the game will be briefly paused for all accounts as the
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 std std-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-none notranslate"><div class="highlight"><pre><span></span> evennia reload
</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>
</section>
<section id="stopping">
<h2>Stopping<a class="headerlink" href="#stopping" 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-none notranslate"><div class="highlight"><pre><span></span> evennia stop
</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>
</section>
<section id="foreground-mode">
<h2>Foreground mode<a class="headerlink" href="#foreground-mode" title="Permalink to this headline"></a></h2>
<p>Normally, Evennia runs as a ‘daemon’, in the background. If you want you can start either of the
processes (but not both) as foreground processes in <em>interactive</em> mode. This means they will log
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-none notranslate"><div class="highlight"><pre><span></span>evennia istart
</pre></div>
</div>
<p>will start/restart the <em>Server</em> in interactive mode. This is required if you want to run a
<a class="reference internal" href="../Coding/Debugging.html"><span class="doc std std-doc">debugger</span></a>. Next time you <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reload</span></code> the server, it will return to normal mode.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia ipstart
</pre></div>
</div>
<p>will start the <em>Portal</em> in interactive mode.</p>
</section>
<section id="resetting">
<h2>Resetting<a class="headerlink" href="#resetting" title="Permalink to this headline"></a></h2>
<p><em>Resetting</em> is the equivalent of a “cold reboot” - the Server will shut down and then restarted
again, but will behave as if it was fully shut down. As opposed to a “real” shutdown, no accounts
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-none notranslate"><div class="highlight"><pre><span></span>evennia reset
</pre></div>
</div>
</section>
<section id="rebooting">
<h2>Rebooting<a class="headerlink" href="#rebooting" title="Permalink to this headline"></a></h2>
<p>This will shut down <em>both</em> Server and Portal, which means all connected players will lose their
connection. It can only be initiated from the terminal:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia reboot
</pre></div>
</div>
<p>This is identical to doing these two commands:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia stop
evennia start
</pre></div>
</div>
</section>
<section id="status-and-info">
<h2>Status and info<a class="headerlink" href="#status-and-info" title="Permalink to this headline"></a></h2>
<p>To check basic Evennia settings, such as which ports and services are active, this will repeat the
initial return given when starting the server:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia info
</pre></div>
</div>
<p>You can also get a briefer run-status from both components with this command</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia status
</pre></div>
</div>
<p>This can be useful for automating checks to make sure the game is running and is responding.</p>
</section>
<section id="killing-linux-mac-only">
<h2>Killing (Linux/Mac only)<a class="headerlink" href="#killing-linux-mac-only" title="Permalink to this headline"></a></h2>
<p>In the extreme case that neither of the server processes locks up and does not respond to commands,
<span class="xref myst"></span>you can send them kill-signals to force them to shut down. To kill only the Server:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia skill
</pre></div>
</div>
<p>To kill both Server and Portal:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia kill
</pre></div>
</div>
<p>Note that this functionality is not supported on Windows.</p>
</section>
<section id="django-options">
<h2>Django options<a class="headerlink" href="#django-options" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia</span></code> program will also pass-through options used by the <code class="docutils literal notranslate"><span class="pre">django-admin</span></code>. These operate on the database in various ways.</p>
<div class="highlight-bash notranslate"><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 the database shell</span>
</pre></div>
</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>
</section>
<section id="advanced-handling-of-evennia-processes">
<h2>Advanced handling of Evennia processes<a class="headerlink" href="#advanced-handling-of-evennia-processes" title="Permalink to this headline"></a></h2>
<p>If you should need to manually manage Evennia’s processors (or view them in a task manager program
such as Linux’ <code class="docutils literal notranslate"><span class="pre">top</span></code> or the more advanced <code class="docutils literal notranslate"><span class="pre">htop</span></code>), you will find the following processes to be
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>
<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-none notranslate"><div class="highlight"><pre><span></span>evennia start
</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>
</section>
</section>
</section>
</div>
</div>
</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="right" >
<a href="Settings.html" title="Game Settings and Configuration direcotry"
>next</a> |</li>
<li class="right" >
<a href="Installation-Non-Interactive.html" title="Non-interactive setup"
>previous</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-1"><a href="Setup-Overview.html" >Server Setup and Life</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Start Stop Reload</a></li>
</ul>
<div class="develop">develop branch</div>
</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.2.1.
</div>
</body>
</html>