diff --git a/docs/source/Setup/Choosing-An-SQL-Server.md b/docs/source/Setup/Choosing-An-SQL-Server.md index 30f854fd17..20c2d8a67f 100644 --- a/docs/source/Setup/Choosing-An-SQL-Server.md +++ b/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//`, where `` and `` 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. \ No newline at end of file +others. If you try other databases out, consider expanding this page with instructions.