Warning: This information is presented as a convenience, using another webserver than Evennia’s own is not directly supported and you are on your own if you want to do so. Evennia’s webserver works out of the box without any extra configuration and also runs in-process making sure to avoid caching race conditions. The browser web client will most likely not work (at least not without tweaking) on a third-party web server.
One reason for wanting to use an external webserver like Apache would be to act as a proxy in front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work covered at the end of this page.
Note that the Apache instructions below might be outdated. If something is not working right, or you use Evennia with a different server, please let us know. Also, if there is a particular Linux distro you would like covered, please let us know.
Apache HTTP Server and mod_wsgi are available in the standard package repositories for Fedora and RHEL:
# dnf install httpd mod_wsgi or # yum install httpd mod_wsgi
Apache HTTP Server and mod_wsgi are available in the standard package repositories for Ubuntu and Debian:
# apt-get update # apt-get install apache2 libapache2-mod-wsgi
Copy and modify the VHOST¶
mod_wsgi is installed, copy the
evennia/web/utils/evennia_wsgi_apache.conf file to your apache2
vhosts/sites folder. On Debian/Ubuntu, this is
/etc/apache2/sites-enabled/. Make your modifications after
copying the file there.
Read the comments and change the paths to point to the appropriate locations within your setup.
You’ll then want to reload or restart apache2 after changing the configurations.
# systemctl restart httpd
# systemctl restart apache2
With any luck, you’ll be able to point your browser at your domain or subdomain that you set up in your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error message and work from there. Questions may be directed to our Evennia Community site.
A note on code reloading¶
mod_wsgi is set up to run on daemon mode (as will be the
case by default on Debian and Ubuntu), you may tell
reload by using the
touch command on
evennia/game/web/utils/apache_wsgi.conf. When mod_wsgi sees that
the file modification time has changed, it will force a code reload. Any
modifications to the code will not be propagated to the live instance of
your site until reloaded.
If you are not running in daemon mode or want to force the issue, simply restart or reload apache2 to apply your changes.
Further notes and hints:¶
If you get strange (and usually uninformative)
errors from Apache, make sure that your
evennia directory is located
in a place the webserver may actually access. For example, some Linux
distributions may default to very restrictive access permissions on a
One user commented that they had to add the following to their Apache config to get things to work. Not confirmed, but worth trying if there are trouble.
<Directory "/home/<yourname>/evennia/game/web"> Options +ExecCGI Allow from all </Directory>
mod_proxy and mod_ssl setup¶
Below are steps on running Evennia using a front-end proxy (Apache HTTP), mod_proxy_http, mod_proxy_wstunnel, and mod_ssl. mod_proxy_http and mod_proxy_wstunnel will simply be referred to as mod_proxy below.
Apache HTTP Server and mod_ssl are available in the standard package repositories for Fedora and RHEL:
# dnf install httpd mod_ssl or # yum install httpd mod_ssl
Apache HTTP Server and mod_ssl are installed together in the
apache2 package and available in the standard package repositories
for Ubuntu and Debian. mod_ssl needs to be enabled after installation:
# apt-get update # apt-get install apache2 # a2enmod ssl
TLS proxy+websocket configuration¶
Below is a sample configuration for Evennia with a TLS-enabled http and websocket proxy.
Apache HTTP Server Configuration¶
<VirtualHost *:80> # Always redirect to https/443 ServerName mud.example.com Redirect / https://mud.example.com </VirtualHost> <VirtualHost *:443> ServerName mud.example.com SSLEngine On # Location of certificate and key SSLCertificateFile /etc/pki/tls/certs/mud.example.com.crt SSLCertificateKeyFile /etc/pki/tls/private/mud.example.com.key # Use a tool https://www.ssllabs.com/ssltest/ to scan your set after setting up. SSLProtocol TLSv1.2 SSLCipherSuite HIGH:!eNULL:!NULL:!aNULL # Proxy all websocket traffic to port 4005 in Evennia ProxyPass /ws ws://127.0.0.1:4005/ ProxyPassReverse /ws ws://127.0.0.1:4005/ # Proxy all HTTP traffic to port 4001 in Evennia ProxyPass / http://127.0.0.1:4001/ ProxyPassReverse / http://127.0.0.1:4001/ # Configure separate logging for this Evennia proxy ErrorLog logs/evennia_error.log CustomLog logs/evennia_access.log combined </VirtualHost>
Evennia secure websocket configuration¶
There is a slight trick in setting up Evennia so websocket traffic is
handled correctly by the proxy. You must set the
WEBSOCKET_CLIENT_URL setting in your
WEBSOCKET_CLIENT_URL = "wss://external.example.com/ws"
The setting above is what the client’s browser will actually use. Note
the use of
wss:// is because our client will be communicating over
an encrypted connection (“wss” indicates websocket over SSL/TLS). Also,
especially note the additional path
/ws at the end of the URL. This
is how Apache HTTP Server identifies that a particular request should be
proxied to Evennia’s websocket port but this should be applicable also
to other types of proxies (like nginx).