initial draft

docs/source/Setup/Configuring-NGINX-for-SSL-with-Evennia.md

@@ -0,0 +1,91 @@
+# Configuring NGIX for SSL with Evennia
+
+> This is NOT a full set-up guide! It assumes you know how to get your own letsencrypt certs, and that you already have nginx installed. **If you don't already use nginx,** you should read the [guide for using HAProxy](link to haproxy guide) instead.
+
+## SSL on the website and websocket
+
+Both the website and the websocket should be accessed through your normal HTTPS port, so they should be defined together.
+
+For nginx, here is an example configuration, using Evennia's default ports:
+```
+server {
+	server_name example.com;
+
+	listen [::]:443 ssl;
+	listen 443 ssl;
+	ssl_certificate	 /path/to/your/cert/file;
+	ssl_certificate_key /path/to/your/cert/key;
+
+	location /ws {
+		# The websocket connection
+		proxy_pass http://localhost:4002;
+		proxy_http_version 1.1;
+		proxy_set_header Upgrade $http_upgrade;
+		proxy_set_header Connection "Upgrade";
+		proxy_set_header Host $host;
+	}
+
+	location / {
+		# The main website
+		proxy_pass http://localhost:4001;
+		proxy_http_version 1.1;
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header Host $http_host;
+		proxy_set_header X-Forwarded-Proto $scheme;
+	}
+}
+```
+
+This proxies the websocket connection through the `/ws` location, and the root location to the website.
+
+Following that example, you then need the following in your `server/conf/secret_settings.py`
+
+> Using `secret_settings.py` for this means you can continue using default access points for local development, making your life easier.
+
+```python
+SERVER_HOSTNAME = "example.com"
+# Set the FULL URI for the websocket, including the scheme
+WEBSOCKET_CLIENT_URL = "wss://example.com/ws"
+# Turn off all external connections
+LOCKDOWN_MODE = True
+```
+This makes sure that evennia uses the correct URI for websocket connections, and also prevents any external connections directly to Evennia's ports, limiting it to connections through the nginx proxies.
+
+## SSL on telnet
+
+If you've only used nginx for websites, telnet is slightly more complicated. You need to set up stream parameters in your primary configuration file, e.g. `/etc/nginx/nginx.conf` - which, at least in my case, was not there by default.
+
+I chose to parallel the `http` structure, so I could have `streams-available` conf files symlinked in `streams-enabled` the same as my sites.
+
+```
+stream {
+	include /etc/nginx/conf.streams.d/*.conf;
+	include /etc/nginx/streams-enabled/*;
+}
+```
+Then of course you need to create the required folders in the same folder:
+
+    $ sudo mkdir conf.streams.d streams-available streams-enabled
+
+An example configuration file for the telnet connection - using an arbitrary external port of `4040` - would then be:
+```
+server {
+	listen [::]:4040 ssl;
+	listen 4040 ssl;
+
+	ssl_certificate	 /path/to/your/cert/file;
+	ssl_certificate_key /path/to/your/cert/key;
+
+	# connect to Evennia's internal telnet port
+	proxy_pass localhost:4000;
+}
+```
+Players can now connect with telnet+SSL to your server at `example.com:4040` - but *not* to the internal connection of `4000`.
+
+> ***! IMPORTANT: The default front page will be WRONG.*** It will show players that they can connect via normal telnet to port 4000, but in fact they will need to connect with telnet+SSL to 4040. You will need to change the `index.html` template and update the telnet section (NOT the telnet ssl section) to display the correct information.
+
+
+## Don't Forget!
+
+`certbot` will automatically renew your certificates for you, but nginx won't see them without reloading. Make sure to set up a monthly cron job to reload your nginx service to avoid service interruptions due to expired certificates.