Merge pull request #1451 from slingamn/mysql_quickstart

add a mysql quickstart guide

docs/MANUAL.md

@@ -40,6 +40,7 @@ _Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn
     - [Language](#language)
     - [Multiclient ("Bouncer")](#multiclient-bouncer)
     - [History](#history)
+    - [Persistent history with MySQL](#persistent-history-with-mysql)
     - [IP cloaking](#ip-cloaking)
     - [Moderation](#moderation)
 - [Frequently Asked Questions](#frequently-asked-questions)
@@ -400,6 +401,30 @@ Unfortunately, client support for history playback is still patchy. In descendin
 1. You can autoreplay a fixed number of lines (e.g., 25) each time you join a channel using `/msg NickServ set autoreplay-lines 25`.
 
 
+## Persistent history with MySQL
+
+On most Linux and POSIX systems, it's straightforward to set up MySQL (or MariaDB) as a backend for persistent history. This increases the amount of history that can be stored, and ensures that message data will be retained on server restart (you can still use the configuration options to set a time limit for retention). Here's a quick start guide for Ubuntu based on [Digital Ocean's documentation](https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04):
+
+1. Install the `mysql-server` package
+1. Run `mysql_secure_installation` as root; this corrects some insecure package defaults
+1. Connect to your new MySQL server as root with `mysql --user root`
+1. In the MySQL prompt, create a new `oragono` user (substitute a strong password of your own for `hunter2`): `CREATE USER 'oragono'@'localhost' IDENTIFIED BY 'hunter2';`
+1. Create the database that history will be stored in: `CREATE DATABASE oragono_history;`
+1. Grant privileges on the database to the new user: `GRANT ALL PRIVILEGES ON oragono_history.* to 'oragono'@'localhost';`
+1. Enable persistent history in your Oragono config file. At a minimum, you must set `history.persistent.enabled = true`. You may want to modify the other options under `history.persistent` and `history`.
+1. Configure Oragono to talk to MySQL (again, substitute the strong password you chose previously for `hunter2`):
+
+```yaml
+    mysql:
+        enabled: true
+        socket-path: "/var/run/mysqld/mysqld.sock"
+        user: "oragono"
+        password: "hunter2"
+        history-database: "oragono_history"
+        timeout: 3s
+```
+
+
 ## IP cloaking
 
 Unlike many other chat and web platforms, IRC traditionally exposes the user's IP and hostname information to other users. This is in part because channel owners and operators (who have privileges over a single channel, but not over the server as a whole) need to be able to ban spammers and abusers from their channels, including via hostnames in cases where the abuser tries to evade the ban.