Maintenance FacadeServer - Headless server with web interface


New Member
Name: FacadeServer

Summary: A program which integrates a Terasology headless (no GUI) server with a web (HTTP and WebSocket) server to allow users to interact with the game using a web browser, a mobile device, or, with a bit of additional work, anything that can interact with an HTTP REST API or a WebSocket connection. Right now, it's possible to use the console/chat system, install modules and manage multiple games (only one can run on the server at a given time).
Scope: It's a facade, like the PC one but headless only and with the addition of the web server.
Current Goal: provide a server with additional features for interaction from outside the regular game client.
Curators: Project started by @msteiger and in large part developed by me (@gianluca_n) as GSoC 2017 project with lot of support from him and @Skaldarnar too (especially in the initial phase).
Related: - web and mobile client based on ReactXP
Download: Docker repository with image updated at the end of GSoC 2017
API documentation: See here if you are interested in developing other clients (programs/scripts which need to interact with this project).



New Member
Hello everyone,

I'm posting here some clarification about the HTTP-HTTPS issues related to FacadeServer's web interface.

When I worked on this project during GSoC 2017 I initially planned to host the web interface on GitHub Pages; in fact, it's available here.
However, later during the summer me and my mentor @msteiger noticed that there was an issue with this setup, arising from these facts:
  • GitHub pages only serves contents through HTTPS. If you try to connect to the plain HTTP link, you are redirected to the HTTPS version.
  • Browsers have a policy to only allow a page served through HTTPS to perform HTTPS requests. This is called the Same-origin policy. Put shortly, the browser will block a page retrieved through HTTPS from opening insecure (http:// or ws://) connections; only secure connections (https:// and wss://) are allowed.
This leads to the fact that if you use a version of the web interface retrieved via HTTPS, like the one from GitHub pages, you won't be able to connect to servers because this is done through an insecure WebSocket connection (ws://). Some browsers (tested: Chrome does, Firefox doesn't) make an exception to the policy for localhost, i.e. you'll still be able to connect to the server if it's running on the same computer you are using the browser on.
Also, if you try to install modules, the web interface will try to connect to the meta server. This is not available over HTTPS, thus it will be blocked by the browser.

As a solution, at the end of the summer I set up a plain HTTP version of the web interface to be hosted from port 8000 of the utility server. As noticed by @Shade254 here, it went down for some time after the utility server was rebooted. I brought it back up yesterday and it seems to be working correctly.

Also, the fact that the identity storage service (port 80 and 443 of the utility server) has been upgraded to HTTPS-only is not a problem. I apologize for creating some confusion in the Slack chat, but I wasn't sure if the same-origin policy also worked the other way round (i.e. page served through HTTP can't open secure connections). It doesn't, i.e. a page served over plain HTTP can open both secure and insecure connections (tested in Firefox and Chrome). So, it can open both the ws:// to the FacadeServer instance (both local or remote), the http:// to the meta server, and the https:// to the identity storage server. However, redirects aren't automatically followed so if you want to use the identity storage service you have to change to in the Server Address field of the login dialog (I think I'll update it to make this the default).

TL;DR: use the instance at It should be working correctly. The one at will only work with localhost, only in certain browsers, and won't allow you to install modules in the server.

In case we want to gradually migrate to an HTTPS-everywhere solution:
  • If we enable HTTPS on the meta server, would have no problems to connect to it (it already does HTTPS connections when connecting to the identity storage service), and module listing from would start working as well.
  • We would also need to implement secure WebSockets in FacadeServer. This is probably quite simple on the technical side (Jetty should have SSL support), but it's probably a hassle for server admins to obtain certificates. I don't know yet how browsers handle self-signed certificates for WebSockets connections opened from a page served over trusted HTTPS.


Docker Dude!
I am always for the HTTPS-everywhere solution.
For serveradmins I would go the self-signed certs way, automatically generated, which may introduce some configuration issues when connection to the server (should be showed in the game, or where ever it may be shown that the server has a self-signed cert. In the case that the serveradmin is able to provide a cert by letsencrypt or some other CA, it should also be stated that the server as such a trusted cert to all users.
There should of course be an easy way to add a trusted cert from an external location to the server (also have to take that into account on the docker images for terasology...)