Merge pull request #2303 from Suudy/feature-advanced-remote-postgresql-use-case

Add section on usage of a remote Postgres database

docs/source/Setup/Choosing-An-SQL-Server.md

@@ -150,6 +150,79 @@ as a shortcut to get into the postgres command line for the right database and u
 With the database setup you should now be able to start start Evennia normally with your new
 database.
 
+### Advanced Usage (Remote Server)
+> :warning: **Warning:** The example below is for a server within a private
+network that is not open to the Internet.  Be sure to understand the details
+before making any changes to an Internet accessible server.
+
+The above discussion is for hosting a local server.  In certain configurations
+it may make sense host the database on a remote server.  One example case is
+where code development may be done on multiple machines by multiple users.  In
+this configuration, a local data base (such as SQLite3) is not feasible
+since all the machines and developers do not have access to the file.
+
+Choose a remote machine to host the database and PostgreSQl server.  Follow
+the instructions [above](#install-and-initial-setup-of-postgresql) on that
+server.  Depending on distribution, PostgreSQL will only accept connections on
+the local machine (localhost).  In order to enable remote access two files
+need to be changed.
+
+First, determine which cluster is running your database.  Use `pg_lscluster`:
+```bash
+$ pg_lsclusters
+Ver Cluster Port Status Owner    Data directory              Log file
+12  main    5432 online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
+```
+
+Next, edit the database's `postgresql.conf`.  This is found on Ubuntu systems
+in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are
+what are reported in the `pg_lscluster` output.  So, for the above example,
+the file is `/etc/postgresql/12/main/postgresql.conf`.
+
+In this file, look for the line with `listen_addresses`.  For example:
+```
+listen_address = 'localhost'    # What IP address(es) to listen on;
+                                # comma-separated list of addresses;
+                                # defaults to 'localhost'; use '*' for all
+```
+> :warning: **Warning:** Misconfiguring the wrong cluster may cause problems
+with existing clusters.
+
+Also, note the line with `port =` and keep the port number in mind.
+
+Set `listen_addresses` to `'*'`.  This permits postgresql to accept connections
+on any interface.
+
+> :warning: **Warning:** Setting `listen_addresses` to `'*'` opens a port on
+all interfaces.  If your server has access to the Internet, ensure your
+firewall is configured appropriately to limit access to this port as necessary.
+(You may also list explicit addresses and subnets to listen.  See the
+postgresql documentation for more details.)
+
+Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`).
+Look for a line with:
+```
+# IPv4 local connections:
+host    all             all             127.0.0.1/32            md5
+```
+Add a line with:
+```
+host    all             all             0.0.0.0/0               md5
+```
+> :warning: **Warning:** This permits incoming connections from *all* IPs.  See the PosgreSQL documentation on how to limit this.
+
+Now, restart your cluster:
+```bash
+$ pg_ctlcluster 12 main restart
+```
+
+Finally, update the database settings in your Evennia secret_settings.py (as
+described [above](#evennia-postgresql-configuration) modifying `SERVER` and
+`PORT` to match your server.
+
+Now your Evennia installation should be able to connect and talk with a remote
+server.
+
 ## MySQL / MariaDB
 
 [MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with
@@ -246,4 +319,4 @@ database.
 
 No testing has been performed with Oracle, but it is also supported through Django. There are
 community maintained drivers for [MS SQL](http://code.google.com/p/django-mssql/) and possibly a few
-others. If you try other databases out, consider expanding this page with instructions.
+others. If you try other databases out, consider expanding this page with instructions.