Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 22:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.0-dev/Setup/Apache-Config.html
Griatch b7ed24bf51 Updated HTML docs
2020-11-14 13:44:49 +01:00

297 lines
No EOL
17 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Apache Config &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="apache-config">
<h1>Apache Config<a class="headerlink" href="#apache-config" title="Permalink to this headline"></a></h1>
<p><strong>Warning</strong>: This information is presented as a convenience, using another webserver than Evennia’s
own is not directly supported and you are on your own if you want to do so. Evennia’s webserver
works out of the box without any extra configuration and also runs in-process making sure to avoid
caching race conditions. The browser web client will most likely not work (at least not without
tweaking) on a third-party web server.</p>
<p>One reason for wanting to use an external webserver like Apache would be to act as a <em>proxy</em> in
front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work
covered at the end of this page.</p>
<p>Note that the Apache instructions below might be outdated. If something is not working right, or you
use Evennia with a different server, please let us know. Also, if there is a particular Linux distro
you would like covered, please let us know.</p>
<div class="section" id="mod-wsgi-setup">
<h2><code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> Setup<a class="headerlink" href="#mod-wsgi-setup" title="Permalink to this headline"></a></h2>
<div class="section" id="install-mod-wsgi">
<h3>Install <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code><a class="headerlink" href="#install-mod-wsgi" title="Permalink to this headline"></a></h3>
<ul>
<li><p><em>Fedora/RHEL</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> are available in the standard package
repositories for Fedora and RHEL:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dnf install httpd mod_wsgi
or
$ yum install httpd mod_wsgi
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> are available in the standard package
repositories for Ubuntu and Debian:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ apt-get update
$ apt-get install apache2 libapache2-mod-wsgi
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="copy-and-modify-the-vhost">
<h3>Copy and modify the VHOST<a class="headerlink" href="#copy-and-modify-the-vhost" title="Permalink to this headline"></a></h3>
<p>After <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is installed, copy the <code class="docutils literal notranslate"><span class="pre">evennia/web/utils/evennia_wsgi_apache.conf</span></code> file to your
apache2 vhosts/sites folder. On Debian/Ubuntu, this is <code class="docutils literal notranslate"><span class="pre">/etc/apache2/sites-enabled/</span></code>. Make your
modifications <strong>after</strong> copying the file there.</p>
<p>Read the comments and change the paths to point to the appropriate locations within your setup.</p>
</div>
<div class="section" id="restart-reload-apache">
<h3>Restart/Reload Apache<a class="headerlink" href="#restart-reload-apache" title="Permalink to this headline"></a></h3>
<p>You’ll then want to reload or restart apache2 after changing the configurations.</p>
<ul>
<li><p><em>Fedora/RHEL/Ubuntu</em></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ systemctl restart httpd
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ systemctl restart apache2
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="enjoy">
<h3>Enjoy<a class="headerlink" href="#enjoy" title="Permalink to this headline"></a></h3>
<p>With any luck, you’ll be able to point your browser at your domain or subdomain that you set up in
your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error
message and work from there. Questions may be directed to our <a class="reference external" href="http://evennia.com">Evennia Community
site</a>.</p>
</div>
<div class="section" id="a-note-on-code-reloading">
<h3>A note on code reloading<a class="headerlink" href="#a-note-on-code-reloading" title="Permalink to this headline"></a></h3>
<p>If your <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> is set up to run on daemon mode (as will be the case by default on Debian and
Ubuntu), you may tell <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> to reload by using the <code class="docutils literal notranslate"><span class="pre">touch</span></code> command on
<code class="docutils literal notranslate"><span class="pre">evennia/game/web/utils/apache_wsgi.conf</span></code>. When <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> sees that the file modification time has
changed, it will force a code reload. Any modifications to the code will not be propagated to the
live instance of your site until reloaded.</p>
<p>If you are not running in daemon mode or want to force the issue, simply restart or reload apache2
to apply your changes.</p>
</div>
<div class="section" id="further-notes-and-hints">
<h3>Further notes and hints:<a class="headerlink" href="#further-notes-and-hints" title="Permalink to this headline"></a></h3>
<p>If you get strange (and usually uninformative) <code class="docutils literal notranslate"><span class="pre">Permission</span> <span class="pre">denied</span></code> errors from Apache, make sure
that your <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory is located in a place the webserver may actually access. For example,
some Linux distributions may default to very restrictive access permissions on a user’s <code class="docutils literal notranslate"><span class="pre">/home</span></code>
directory.</p>
<p>One user commented that they had to add the following to their Apache config to get things to work.
Not confirmed, but worth trying if there are trouble.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Directory</span> <span class="s2">&quot;/home/&lt;yourname&gt;/evennia/game/web&quot;</span><span class="o">&gt;</span>
<span class="n">Options</span> <span class="o">+</span><span class="n">ExecCGI</span>
<span class="n">Allow</span> <span class="kn">from</span> <span class="nn">all</span>
<span class="o">&lt;/</span><span class="n">Directory</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="mod-proxy-and-mod-ssl-setup">
<h2><code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> setup<a class="headerlink" href="#mod-proxy-and-mod-ssl-setup" title="Permalink to this headline"></a></h2>
<p>Below are steps on running Evennia using a front-end proxy (Apache HTTP), <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code>,
<code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code>, and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code>. <code class="docutils literal notranslate"><span class="pre">mod_proxy_http</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_proxy_wstunnel</span></code> will simply be
referred to as
<code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> below.</p>
<div class="section" id="install-mod-ssl">
<h3>Install <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code><a class="headerlink" href="#install-mod-ssl" title="Permalink to this headline"></a></h3>
<ul>
<li><p><em>Fedora/RHEL</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> are available in the standard package
repositories for Fedora and RHEL:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dnf install httpd mod_ssl
or
$ yum install httpd mod_ssl
</pre></div>
</div>
</li>
<li><p><em>Ubuntu/Debian</em> - Apache HTTP Server and <code class="docutils literal notranslate"><span class="pre">mod_sslj</span></code>kl are installed together in the <code class="docutils literal notranslate"><span class="pre">apache2</span></code>
package and available in the
standard package repositories for Ubuntu and Debian. <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> needs to be enabled after
installation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ apt-get update
$ apt-get install apache2
$ a2enmod ssl
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="tls-proxy-websocket-configuration">
<h3>TLS proxy+websocket configuration<a class="headerlink" href="#tls-proxy-websocket-configuration" title="Permalink to this headline"></a></h3>
<p>Below is a sample configuration for Evennia with a TLS-enabled http and websocket proxy.</p>
<div class="section" id="apache-http-server-configuration">
<h4>Apache HTTP Server Configuration<a class="headerlink" href="#apache-http-server-configuration" title="Permalink to this headline"></a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>&lt;VirtualHost *:80&gt;
# Always redirect to https/443
ServerName mud.example.com
Redirect / https://mud.example.com
&lt;/VirtualHost&gt;
&lt;VirtualHost *:443&gt;
ServerName mud.example.com
SSLEngine On
# Location of certificate and key
SSLCertificateFile /etc/pki/tls/certs/mud.example.com.crt
SSLCertificateKeyFile /etc/pki/tls/private/mud.example.com.key
# Use a tool https://www.ssllabs.com/ssltest/ to scan your set after setting up.
SSLProtocol TLSv1.2
SSLCipherSuite HIGH:!eNULL:!NULL:!aNULL
# Proxy all websocket traffic to port 4002 in Evennia
ProxyPass /ws ws://127.0.0.1:4002/
ProxyPassReverse /ws ws://127.0.0.1:4002/
# Proxy all HTTP traffic to port 4001 in Evennia
ProxyPass / http://127.0.0.1:4001/
ProxyPassReverse / http://127.0.0.1:4001/
# Configure separate logging for this Evennia proxy
ErrorLog logs/evennia_error.log
CustomLog logs/evennia_access.log combined
&lt;/VirtualHost&gt;
</pre></div>
</div>
</div>
<div class="section" id="evennia-secure-websocket-configuration">
<h4>Evennia secure websocket configuration<a class="headerlink" href="#evennia-secure-websocket-configuration" title="Permalink to this headline"></a></h4>
<p>There is a slight trick in setting up Evennia so websocket traffic is handled correctly by the
proxy. You must set the <code class="docutils literal notranslate"><span class="pre">WEBSOCKET_CLIENT_URL</span></code> setting in your <code class="docutils literal notranslate"><span class="pre">mymud/server/conf/settings.py</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">WEBSOCKET_CLIENT_URL</span> <span class="o">=</span> <span class="s2">&quot;wss://external.example.com/ws&quot;</span>
</pre></div>
</div>
<p>The setting above is what the client’s browser will actually use. Note the use of <code class="docutils literal notranslate"><span class="pre">wss://</span></code> is
because our client will be communicating over an encrypted connection (“wss” indicates websocket
over SSL/TLS). Also, especially note the additional path <code class="docutils literal notranslate"><span class="pre">/ws</span></code> at the end of the URL. This is how
Apache HTTP Server identifies that a particular request should be proxied to Evennia’s websocket
port but this should be applicable also to other types of proxies (like nginx).</p>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Apache Config</a><ul>
<li><a class="reference internal" href="#mod-wsgi-setup"><code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code> Setup</a><ul>
<li><a class="reference internal" href="#install-mod-wsgi">Install <code class="docutils literal notranslate"><span class="pre">mod_wsgi</span></code></a></li>
<li><a class="reference internal" href="#copy-and-modify-the-vhost">Copy and modify the VHOST</a></li>
<li><a class="reference internal" href="#restart-reload-apache">Restart/Reload Apache</a></li>
<li><a class="reference internal" href="#enjoy">Enjoy</a></li>
<li><a class="reference internal" href="#a-note-on-code-reloading">A note on code reloading</a></li>
<li><a class="reference internal" href="#further-notes-and-hints">Further notes and hints:</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mod-proxy-and-mod-ssl-setup"><code class="docutils literal notranslate"><span class="pre">mod_proxy</span></code> and <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code> setup</a><ul>
<li><a class="reference internal" href="#install-mod-ssl">Install <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code></a></li>
<li><a class="reference internal" href="#tls-proxy-websocket-configuration">TLS proxy+websocket configuration</a><ul>
<li><a class="reference internal" href="#apache-http-server-configuration">Apache HTTP Server Configuration</a></li>
<li><a class="reference internal" href="#evennia-secure-websocket-configuration">Evennia secure websocket configuration</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Setup/Apache-Config.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Apache-Config.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Apache Config</a></li>
</ul>
<div 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>
Reference in a new issue View git blame Copy permalink