diff --git a/docs/source/Setup/Configuring-NGINX-for-SSL-with-Evennia.md b/docs/source/Setup/Configuring-NGINX-for-SSL-with-Evennia.md new file mode 100644 index 0000000000..b6464d44ba --- /dev/null +++ b/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.