Merge pull request #3105 from InspectorCaracal/nginx-config

Documentation page for NGINX configuration

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

@@ -0,0 +1,100 @@
+# Configuring NGINX for Evennia with SSL
+
+> This is NOT a full set-up guide! It assumes you know how to get your own letsencrypt certs, that you already have nginx installed, and that you are familiar with nginx configuration files. **If you don't already use nginx,** you should follow the [guide for using HAProxy](Config-HAProxy) 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;
+		# allows the handshake to upgrade the connection
+		proxy_set_header Upgrade $http_upgrade;
+		proxy_set_header Connection "Upgrade";
+		# forwards the connection IP
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header Host $host;
+	}
+
+	location / {
+		# The main website
+		proxy_pass http://localhost:4001;
+		proxy_http_version 1.1;
+		# forwards the connection IP
+		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. Setting `LOCKDOWN_MODE` on will also prevents any external connections directly to Evennia's ports, limiting it to connections through the nginx proxies.
+
+## SSL on telnet
+
+> This will proxy ALL telnet access through nginx! If you want players to connect directly to Evennia's telnet ports instead of going through nginx, leave `LOCKDOWN_MODE` off and use a different SSL implementation.
+
+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 NON-SSL telnet port
+	proxy_pass localhost:4000;
+	# forwards the connection IP - requires --with-stream-realip-module
+	set_real_ip_from $realip_remote_addr:$realip_remote_port
+}
+```
+Players can now connect with telnet+SSL to your server at `example.com:4040` - but *not* to the internal connection of `4000`.
+
+> ***IMPORTANT: With this configuration, the default front page will be WRONG.*** 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.